sessions, LifecycleEventDispatcher lifecycleDispatcher,
- Executor executor) {
+ Executor executor, GitHubTokenProviderRegistry gitHubTokenProviders) {
this.sessions = sessions;
this.lifecycleDispatcher = lifecycleDispatcher;
this.executor = executor;
+ this.gitHubTokenProviders = gitHubTokenProviders;
}
/**
@@ -92,6 +99,71 @@ void registerHandlers(JsonRpcClient rpc) {
(requestId, params) -> handleSystemMessageTransform(rpc, requestId, params));
rpc.registerMethodHandler("providerToken.getToken",
(requestId, params) -> handleProviderTokenGetToken(rpc, requestId, params));
+ rpc.registerMethodHandler("gitHubToken.getToken",
+ (requestId, params) -> handleGitHubTokenGetToken(rpc, requestId, params));
+ }
+
+ private void handleGitHubTokenGetToken(JsonRpcClient rpc, String requestId, JsonNode params) {
+ runAsync(() -> {
+ final long requestIdLong = parseRequestId(requestId, "gitHubToken.getToken");
+ if (requestIdLong == -1) {
+ return;
+ }
+ try {
+ GitHubTokenAcquireRequest request = MAPPER.treeToValue(params, GitHubTokenAcquireRequest.class);
+ var provider = gitHubTokenProviders.get(request.registrationId());
+ if (provider == null) {
+ rpc.sendErrorResponse(requestIdLong, -32603, "Unknown GitHub token provider registration");
+ return;
+ }
+
+ var resultFuture = provider
+ .getToken(new GitHubTokenProviderArgs(request.host(), request.sessionId(), request.reason()));
+ if (resultFuture == null) {
+ rpc.sendErrorResponse(requestIdLong, -32603, "GitHub token provider returned a null future");
+ return;
+ }
+ resultFuture.thenAccept(result -> sendGitHubTokenResult(rpc, requestIdLong, result))
+ .exceptionally(error -> {
+ try {
+ Throwable cause = error instanceof java.util.concurrent.CompletionException
+ && error.getCause() != null ? error.getCause() : error;
+ rpc.sendErrorResponse(requestIdLong, -32603,
+ "GitHub token provider failed: " + cause.getMessage());
+ } catch (IOException sendError) {
+ LOG.log(Level.SEVERE, "Error sending GitHub token provider error", sendError);
+ }
+ return null;
+ });
+ } catch (Exception error) {
+ try {
+ rpc.sendErrorResponse(requestIdLong, -32603,
+ "GitHub token provider handler failed: " + error.getMessage());
+ } catch (IOException sendError) {
+ LOG.log(Level.SEVERE, "Error sending GitHub token provider handler error", sendError);
+ }
+ }
+ });
+ }
+
+ private void sendGitHubTokenResult(JsonRpcClient rpc, long requestId, GitHubTokenProviderResult result) {
+ try {
+ if (result == null) {
+ rpc.sendErrorResponse(requestId, -32603, "GitHub token provider returned a null result");
+ return;
+ }
+ if (result.isCancelled()) {
+ rpc.sendResponse(requestId, new GitHubTokenAcquireResultCancelled());
+ return;
+ }
+ var wireResult = new GitHubTokenAcquireResultToken();
+ wireResult.setAccessToken(result.getAccessToken());
+ wireResult.setExpiresIn(result.getExpiresIn());
+ wireResult.setTokenType(result.getTokenType());
+ rpc.sendResponse(requestId, wireResult);
+ } catch (IOException error) {
+ LOG.log(Level.SEVERE, "Error sending GitHub token provider result", error);
+ }
}
private void handleSessionEvent(JsonNode params) {
diff --git a/java/sdk/src/main/java/com/github/copilot/rpc/CreateSessionRequest.java b/java/sdk/src/main/java/com/github/copilot/rpc/CreateSessionRequest.java
index 2eab977db..403893987 100644
--- a/java/sdk/src/main/java/com/github/copilot/rpc/CreateSessionRequest.java
+++ b/java/sdk/src/main/java/com/github/copilot/rpc/CreateSessionRequest.java
@@ -224,6 +224,9 @@ public final class CreateSessionRequest {
@JsonProperty("gitHubToken")
private String gitHubToken;
+ @JsonProperty("gitHubTokenProviderRegistrationId")
+ private String gitHubTokenProviderRegistrationId;
+
@JsonProperty("remoteSession")
private String remoteSession;
@@ -1061,6 +1064,21 @@ public void setGitHubToken(String gitHubToken) {
this.gitHubToken = gitHubToken;
}
+ /**
+ * Gets the token-provider registration ID. @return the opaque registration ID
+ */
+ public String getGitHubTokenProviderRegistrationId() {
+ return gitHubTokenProviderRegistrationId;
+ }
+
+ /**
+ * Sets the token-provider registration ID. @param registrationId the opaque
+ * registration ID
+ */
+ public void setGitHubTokenProviderRegistrationId(String registrationId) {
+ this.gitHubTokenProviderRegistrationId = registrationId;
+ }
+
/** Gets the remote session mode. @return the remote session mode */
public String getRemoteSession() {
return remoteSession;
diff --git a/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProvider.java b/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProvider.java
new file mode 100644
index 000000000..daefc2f8d
--- /dev/null
+++ b/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProvider.java
@@ -0,0 +1,31 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.rpc;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Acquires rotating GitHub tokens for one session.
+ *
+ * Implementations return either a token with a positive remaining lifetime or
+ * an explicit cancellation. Production GitHub tokens typically last eight
+ * hours. Initial cancellation, callback errors, and invalid token responses
+ * reject session creation or resume instead of falling back to ambient
+ * authentication.
+ *
+ * @since 1.0.0
+ */
+@FunctionalInterface
+public interface GitHubTokenProvider {
+
+ /**
+ * Acquires a GitHub token for the supplied host and session context.
+ *
+ * @param args
+ * callback context
+ * @return a future containing a token or cancellation result
+ */
+ CompletableFuture getToken(GitHubTokenProviderArgs args);
+}
diff --git a/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProviderArgs.java b/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProviderArgs.java
new file mode 100644
index 000000000..283d3c4c7
--- /dev/null
+++ b/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProviderArgs.java
@@ -0,0 +1,22 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.rpc;
+
+import com.github.copilot.generated.rpc.GitHubTokenAcquireReason;
+
+/**
+ * Context supplied when a session needs a GitHub token.
+ *
+ * @param host
+ * effective GitHub host for which a token is required
+ * @param sessionId
+ * session receiving the token, or {@code null} before a cloud
+ * session has been assigned an ID
+ * @param reason
+ * whether this is the initial acquisition or a refresh
+ * @since 1.0.0
+ */
+public record GitHubTokenProviderArgs(String host, String sessionId, GitHubTokenAcquireReason reason) {
+}
diff --git a/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProviderResult.java b/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProviderResult.java
new file mode 100644
index 000000000..942528643
--- /dev/null
+++ b/java/sdk/src/main/java/com/github/copilot/rpc/GitHubTokenProviderResult.java
@@ -0,0 +1,113 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.rpc;
+
+import java.util.Objects;
+
+/**
+ * Result of acquiring a session-scoped GitHub token.
+ *
+ * Token values are redacted from {@link #toString()}.
+ *
+ * @since 1.0.0
+ */
+public final class GitHubTokenProviderResult {
+
+ private final String accessToken;
+ private final long expiresIn;
+ private final String tokenType;
+ private final boolean cancelled;
+
+ private GitHubTokenProviderResult(String accessToken, long expiresIn, String tokenType, boolean cancelled) {
+ this.accessToken = accessToken;
+ this.expiresIn = expiresIn;
+ this.tokenType = tokenType;
+ this.cancelled = cancelled;
+ }
+
+ /**
+ * Creates a token result.
+ *
+ * @param accessToken
+ * GitHub access token
+ * @param expiresIn
+ * positive remaining lifetime in seconds when the callback completes
+ * @return the token result
+ */
+ public static GitHubTokenProviderResult token(String accessToken, long expiresIn) {
+ return token(accessToken, expiresIn, null);
+ }
+
+ /**
+ * Creates a token result with an explicit OAuth token type.
+ *
+ * @param accessToken
+ * GitHub access token
+ * @param expiresIn
+ * positive remaining lifetime in seconds when the callback completes
+ * @param tokenType
+ * OAuth token type, or {@code null} to use the runtime's bearer
+ * default
+ * @return the token result
+ */
+ public static GitHubTokenProviderResult token(String accessToken, long expiresIn, String tokenType) {
+ Objects.requireNonNull(accessToken, "accessToken must not be null");
+ return new GitHubTokenProviderResult(accessToken, expiresIn, tokenType, false);
+ }
+
+ /**
+ * Creates an explicit cancellation result.
+ *
+ * @return the cancellation result
+ */
+ public static GitHubTokenProviderResult cancelled() {
+ return new GitHubTokenProviderResult(null, 0, null, true);
+ }
+
+ /**
+ * Gets whether acquisition was cancelled.
+ *
+ * @return {@code true} for a cancellation result
+ */
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ /**
+ * Gets the access token.
+ *
+ * @return the token, or {@code null} for cancellation
+ */
+ public String getAccessToken() {
+ return accessToken;
+ }
+
+ /**
+ * Gets the remaining token lifetime.
+ *
+ * @return remaining lifetime in seconds
+ */
+ public long getExpiresIn() {
+ return expiresIn;
+ }
+
+ /**
+ * Gets the OAuth token type.
+ *
+ * @return token type, or {@code null} for the runtime default
+ */
+ public String getTokenType() {
+ return tokenType;
+ }
+
+ @Override
+ public String toString() {
+ if (cancelled) {
+ return "GitHubTokenProviderResult{cancelled}";
+ }
+ return "GitHubTokenProviderResult{accessToken=, expiresIn=" + expiresIn + ", tokenType=" + tokenType
+ + "}";
+ }
+}
diff --git a/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java b/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java
index a18803637..76b6e26a7 100644
--- a/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java
+++ b/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java
@@ -105,6 +105,8 @@ public class ResumeSessionConfig {
private boolean enableMcpApps;
private GitHubMcpToolConfig githubMcpToolConfig;
private String gitHubToken;
+ @JsonIgnore
+ private GitHubTokenProvider gitHubTokenProvider;
private String remoteSession;
private CopilotExpAssignmentResponse expAssignments;
private Boolean enableManagedSettings;
@@ -1864,6 +1866,33 @@ public ResumeSessionConfig setGitHubToken(String gitHubToken) {
return this;
}
+ /**
+ * Gets the rotating GitHub token provider for the resumed session.
+ *
+ * @return the provider, or {@code null} when a static token is used
+ */
+ public GitHubTokenProvider getGitHubTokenProvider() {
+ return gitHubTokenProvider;
+ }
+
+ /**
+ * Sets the rotating GitHub token provider for the resumed session.
+ *
+ * The provider receives only the effective host, optional assigned session ID,
+ * and acquisition reason. It must return a positive remaining lifetime in
+ * seconds when its callback completes. Production GitHub tokens typically last
+ * eight hours. This option is mutually exclusive with
+ * {@link #setGitHubToken(String)}.
+ *
+ * @param gitHubTokenProvider
+ * provider used for initial acquisition and refresh
+ * @return this config instance for method chaining
+ */
+ public ResumeSessionConfig setGitHubTokenProvider(GitHubTokenProvider gitHubTokenProvider) {
+ this.gitHubTokenProvider = gitHubTokenProvider;
+ return this;
+ }
+
/**
* Gets the per-session remote behavior control.
*
@@ -2045,6 +2074,7 @@ public ResumeSessionConfig clone() {
copy.enableMcpApps = this.enableMcpApps;
copy.githubMcpToolConfig = this.githubMcpToolConfig;
copy.gitHubToken = this.gitHubToken;
+ copy.gitHubTokenProvider = this.gitHubTokenProvider;
copy.remoteSession = this.remoteSession;
copy.expAssignments = this.expAssignments;
copy.enableManagedSettings = this.enableManagedSettings;
diff --git a/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionRequest.java b/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionRequest.java
index e52892477..9b8e897fd 100644
--- a/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionRequest.java
+++ b/java/sdk/src/main/java/com/github/copilot/rpc/ResumeSessionRequest.java
@@ -229,6 +229,9 @@ public final class ResumeSessionRequest {
@JsonProperty("gitHubToken")
private String gitHubToken;
+ @JsonProperty("gitHubTokenProviderRegistrationId")
+ private String gitHubTokenProviderRegistrationId;
+
@JsonProperty("remoteSession")
private String remoteSession;
@@ -1086,6 +1089,21 @@ public void setGitHubToken(String gitHubToken) {
this.gitHubToken = gitHubToken;
}
+ /**
+ * Gets the token-provider registration ID. @return the opaque registration ID
+ */
+ public String getGitHubTokenProviderRegistrationId() {
+ return gitHubTokenProviderRegistrationId;
+ }
+
+ /**
+ * Sets the token-provider registration ID. @param registrationId the opaque
+ * registration ID
+ */
+ public void setGitHubTokenProviderRegistrationId(String registrationId) {
+ this.gitHubTokenProviderRegistrationId = registrationId;
+ }
+
/** Gets the remote session mode. @return the remote session mode */
public String getRemoteSession() {
return remoteSession;
diff --git a/java/sdk/src/main/java/com/github/copilot/rpc/SessionConfig.java b/java/sdk/src/main/java/com/github/copilot/rpc/SessionConfig.java
index 1127e6777..4e9ede73d 100644
--- a/java/sdk/src/main/java/com/github/copilot/rpc/SessionConfig.java
+++ b/java/sdk/src/main/java/com/github/copilot/rpc/SessionConfig.java
@@ -105,6 +105,8 @@ public class SessionConfig {
private boolean enableMcpApps;
private GitHubMcpToolConfig githubMcpToolConfig;
private String gitHubToken;
+ @JsonIgnore
+ private GitHubTokenProvider gitHubTokenProvider;
private String remoteSession;
private CloudSessionOptions cloud;
private CopilotExpAssignmentResponse expAssignments;
@@ -1945,6 +1947,33 @@ public SessionConfig setGitHubToken(String gitHubToken) {
return this;
}
+ /**
+ * Gets the rotating GitHub token provider for this session.
+ *
+ * @return the provider, or {@code null} when a static token is used
+ */
+ public GitHubTokenProvider getGitHubTokenProvider() {
+ return gitHubTokenProvider;
+ }
+
+ /**
+ * Sets the rotating GitHub token provider for this session.
+ *
+ * The provider receives only the effective host, optional assigned session ID,
+ * and acquisition reason. It must return a positive remaining lifetime in
+ * seconds when its callback completes. Production GitHub tokens typically last
+ * eight hours. This option is mutually exclusive with
+ * {@link #setGitHubToken(String)}.
+ *
+ * @param gitHubTokenProvider
+ * provider used for initial acquisition and refresh
+ * @return this config instance for method chaining
+ */
+ public SessionConfig setGitHubTokenProvider(GitHubTokenProvider gitHubTokenProvider) {
+ this.gitHubTokenProvider = gitHubTokenProvider;
+ return this;
+ }
+
/**
* Gets the per-session remote behavior control.
*
@@ -2063,10 +2092,11 @@ public Optional getEnableManagedSettings() {
* (bypass-permissions policy) at session bootstrap.
*
* When {@code true}, the runtime self-fetches enterprise managed settings using
- * the session's {@link #getGitHubToken() gitHubToken}. Requires
- * {@code gitHubToken} to be set; if omitted, the runtime is expected to reject
- * session creation (fail-closed). When unset, behaves exactly as before.
- * Serialized on the wire as {@code enableManagedSettings}.
+ * the session's static {@link #getGitHubToken() gitHubToken} or
+ * {@link #getGitHubTokenProvider() gitHubTokenProvider}. Requires one of those
+ * credentials; if both are omitted, the runtime is expected to reject session
+ * creation (fail-closed). When unset, behaves exactly as before. Serialized on
+ * the wire as {@code enableManagedSettings}.
*
* @param enableManagedSettings
* {@code true} to opt into self-fetching managed settings
@@ -2184,6 +2214,7 @@ public SessionConfig clone() {
copy.enableMcpApps = this.enableMcpApps;
copy.githubMcpToolConfig = this.githubMcpToolConfig;
copy.gitHubToken = this.gitHubToken;
+ copy.gitHubTokenProvider = this.gitHubTokenProvider;
copy.remoteSession = this.remoteSession;
copy.cloud = this.cloud;
copy.expAssignments = this.expAssignments;
diff --git a/java/sdk/src/test/java/com/github/copilot/CopilotClientTest.java b/java/sdk/src/test/java/com/github/copilot/CopilotClientTest.java
index 067571df1..4cfd7f4c4 100644
--- a/java/sdk/src/test/java/com/github/copilot/CopilotClientTest.java
+++ b/java/sdk/src/test/java/com/github/copilot/CopilotClientTest.java
@@ -8,6 +8,8 @@
import org.junit.jupiter.api.Test;
import com.github.copilot.rpc.CopilotClientOptions;
+import com.github.copilot.rpc.DeleteSessionResponse;
+import com.github.copilot.rpc.GitHubTokenProviderResult;
import com.github.copilot.rpc.PermissionHandler;
import com.github.copilot.rpc.PingResponse;
import com.github.copilot.rpc.SessionConfig;
@@ -111,6 +113,35 @@ void testForceStopAndExternalStopDoNotRequestRuntimeShutdown() throws Exception
verify(externalRpc, never()).invoke(eq("runtime.shutdown"), any(), eq(Void.class));
}
+ @Test
+ @SuppressWarnings("unchecked")
+ void testDeleteSessionReleasesGitHubTokenProvider() throws Exception {
+ var client = new CopilotClient(new CopilotClientOptions().setAutoStart(false));
+ var rpc = mock(JsonRpcClient.class);
+ when(rpc.invoke(eq("session.delete"), any(), eq(DeleteSessionResponse.class)))
+ .thenReturn(CompletableFuture.completedFuture(new DeleteSessionResponse(true, null)));
+ when(rpc.invoke(eq("session.destroy"), any(), eq(Void.class)))
+ .thenReturn(CompletableFuture.completedFuture(null));
+ setConnectionFuture(client, rpc, null);
+
+ var registry = new GitHubTokenProviderRegistry();
+ var registration = registry
+ .register(args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()));
+ var session = new CopilotSession("delete-session", rpc);
+ session.setGitHubTokenProviderRegistration(registration);
+ Field sessionsField = CopilotClient.class.getDeclaredField("sessions");
+ sessionsField.setAccessible(true);
+ ((Map) sessionsField.get(client)).put(session.getSessionId(), session);
+
+ try {
+ client.deleteSession(session.getSessionId()).join();
+ assertNull(registry.get(registration.id()));
+ } finally {
+ session.close();
+ client.close();
+ }
+ }
+
@Test
void testClientConstruction() {
var client = new CopilotClient();
diff --git a/java/sdk/src/test/java/com/github/copilot/GitHubTokenProviderRegistryTest.java b/java/sdk/src/test/java/com/github/copilot/GitHubTokenProviderRegistryTest.java
new file mode 100644
index 000000000..8f2c7d331
--- /dev/null
+++ b/java/sdk/src/test/java/com/github/copilot/GitHubTokenProviderRegistryTest.java
@@ -0,0 +1,74 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+
+import org.junit.jupiter.api.Test;
+
+import com.github.copilot.rpc.GitHubTokenProviderResult;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.ResumeSessionConfig;
+import com.github.copilot.rpc.SessionConfig;
+
+class GitHubTokenProviderRegistryTest {
+
+ @Test
+ void staticTokenAndProviderAreMutuallyExclusive() {
+ try (var client = new CopilotClient()) {
+ var create = new SessionConfig().setGitHubToken("static")
+ .setGitHubTokenProvider(
+ args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()))
+ .setOnPermissionRequest(PermissionHandler.APPROVE_ALL);
+ var createError = assertThrows(CompletionException.class, () -> client.createSession(create).join());
+ assertInstanceOf(IllegalArgumentException.class, createError.getCause());
+
+ var resume = new ResumeSessionConfig().setGitHubToken("static")
+ .setGitHubTokenProvider(
+ args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()))
+ .setOnPermissionRequest(PermissionHandler.APPROVE_ALL);
+ var resumeError = assertThrows(CompletionException.class,
+ () -> client.resumeSession("session", resume).join());
+ assertInstanceOf(IllegalArgumentException.class, resumeError.getCause());
+ }
+ }
+
+ @Test
+ void registrationRollbackAndResumeReplacementAreIsolated() {
+ var registry = new GitHubTokenProviderRegistry();
+ var first = registry.register(args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()));
+ var second = registry
+ .register(args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()));
+
+ assertNotNull(registry.get(first.id()));
+ assertNotNull(registry.get(second.id()));
+ first.claim("session-1");
+ second.claim("session-1");
+ assertNull(registry.get(first.id()));
+ assertNotNull(registry.get(second.id()));
+
+ first.close();
+ assertNotNull(registry.get(second.id()));
+ second.close();
+ assertNull(registry.get(second.id()));
+
+ var retired = registry
+ .register(args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()));
+ retired.claim("session-2");
+ registry.retire("session-2");
+ assertNull(registry.get(retired.id()));
+
+ var failed = registry
+ .register(args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()));
+ failed.close();
+ assertNull(registry.get(failed.id()));
+ }
+}
diff --git a/java/sdk/src/test/java/com/github/copilot/JsonRpcClientTest.java b/java/sdk/src/test/java/com/github/copilot/JsonRpcClientTest.java
index 79aaea10d..009f15c20 100644
--- a/java/sdk/src/test/java/com/github/copilot/JsonRpcClientTest.java
+++ b/java/sdk/src/test/java/com/github/copilot/JsonRpcClientTest.java
@@ -115,6 +115,22 @@ void testNotify() throws Exception {
}
}
+ @Test
+ void testCredentialValuesAreRedactedOnlyFromDiagnosticRendering() throws Exception {
+ String json = """
+ {"jsonrpc":"2.0","result":{"accessToken":"secret","nested":{"gitHubToken":"static"}},
+ "metadata":{"tokenType":"Bearer"}}
+ """;
+
+ String rendered = JsonRpcClient.redactCredentialsForLogging(json);
+
+ assertFalse(rendered.contains("secret"));
+ assertFalse(rendered.contains("static"));
+ assertEquals("", MAPPER.readTree(rendered).at("/result/accessToken").asText());
+ assertEquals("", MAPPER.readTree(rendered).at("/result/nested/gitHubToken").asText());
+ assertEquals("Bearer", MAPPER.readTree(rendered).at("/metadata/tokenType").asText());
+ }
+
// ---- isConnected() ----
@Test
diff --git a/java/sdk/src/test/java/com/github/copilot/RpcHandlerDispatcherTest.java b/java/sdk/src/test/java/com/github/copilot/RpcHandlerDispatcherTest.java
index 76c2d41b2..1cb3ae82e 100644
--- a/java/sdk/src/test/java/com/github/copilot/RpcHandlerDispatcherTest.java
+++ b/java/sdk/src/test/java/com/github/copilot/RpcHandlerDispatcherTest.java
@@ -15,6 +15,7 @@
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.atomic.AtomicReference;
import java.util.function.BiConsumer;
import org.junit.jupiter.api.AfterEach;
@@ -32,6 +33,9 @@
import com.github.copilot.rpc.ToolDefinition;
import com.github.copilot.rpc.ToolResultObject;
import com.github.copilot.rpc.UserInputResponse;
+import com.github.copilot.generated.rpc.GitHubTokenAcquireReason;
+import com.github.copilot.rpc.GitHubTokenProviderArgs;
+import com.github.copilot.rpc.GitHubTokenProviderResult;
/**
* Unit tests for {@link RpcHandlerDispatcher} focusing on coverage gaps
@@ -51,6 +55,7 @@ class RpcHandlerDispatcherTest {
private RpcHandlerDispatcher dispatcher;
private InputStream responseStream;
private Map> handlers;
+ private GitHubTokenProviderRegistry gitHubTokenProviders;
@BeforeEach
void setup() throws Exception {
@@ -66,7 +71,8 @@ void setup() throws Exception {
sessions = new ConcurrentHashMap<>();
lifecycleEvents = new CopyOnWriteArrayList<>();
- dispatcher = new RpcHandlerDispatcher(sessions, lifecycleEvents::add, null);
+ gitHubTokenProviders = new GitHubTokenProviderRegistry();
+ dispatcher = new RpcHandlerDispatcher(sessions, lifecycleEvents::add, null, gitHubTokenProviders);
dispatcher.registerHandlers(rpc);
// Extract the registered handlers via reflection so we can invoke them directly
@@ -119,6 +125,57 @@ private CopilotSession createSession(String sessionId) {
return session;
}
+ @Test
+ void gitHubTokenCallbackMapsRequestAndTokenResult() throws Exception {
+ AtomicReference received = new AtomicReference<>();
+ var registration = gitHubTokenProviders.register(args -> {
+ received.set(args);
+ return CompletableFuture.completedFuture(GitHubTokenProviderResult.token("secret", 28_800, "bearer"));
+ });
+ ObjectNode params = MAPPER.createObjectNode();
+ params.put("registrationId", registration.id());
+ params.put("host", "github.example");
+ params.put("sessionId", "session-1");
+ params.put("reason", "initial");
+
+ invokeHandler("gitHubToken.getToken", "80", params);
+
+ JsonNode response = readResponse();
+ assertEquals("token", response.at("/result/kind").asText());
+ assertEquals("secret", response.at("/result/accessToken").asText());
+ assertEquals(28_800, response.at("/result/expiresIn").asLong());
+ assertEquals("github.example", received.get().host());
+ assertEquals("session-1", received.get().sessionId());
+ assertEquals(GitHubTokenAcquireReason.INITIAL, received.get().reason());
+ }
+
+ @Test
+ void gitHubTokenCallbackPreservesCancellationAndErrors() throws Exception {
+ var cancelled = gitHubTokenProviders
+ .register(args -> CompletableFuture.completedFuture(GitHubTokenProviderResult.cancelled()));
+ ObjectNode cancelledParams = MAPPER.createObjectNode();
+ cancelledParams.put("registrationId", cancelled.id());
+ cancelledParams.put("host", "github.com");
+ cancelledParams.put("reason", "refresh");
+ invokeHandler("gitHubToken.getToken", "81", cancelledParams);
+ assertEquals("cancelled", readResponse().at("/result/kind").asText());
+
+ var failed = gitHubTokenProviders.register(
+ args -> CompletableFuture.failedFuture(new IllegalStateException("credential service unavailable")));
+ ObjectNode failedParams = cancelledParams.deepCopy();
+ failedParams.put("registrationId", failed.id());
+ invokeHandler("gitHubToken.getToken", "82", failedParams);
+ JsonNode error = readResponse();
+ assertEquals(-32603, error.at("/error/code").asInt());
+ assertTrue(error.at("/error/message").asText().contains("credential service unavailable"));
+
+ failedParams.put("registrationId", "unknown");
+ invokeHandler("gitHubToken.getToken", "83", failedParams);
+ JsonNode unknown = readResponse();
+ assertEquals(-32603, unknown.at("/error/code").asInt());
+ assertTrue(unknown.at("/error/message").asText().contains("Unknown GitHub token provider registration"));
+ }
+
// ===== session.event tests =====
@Test
diff --git a/java/sdk/src/test/java/com/github/copilot/SessionRequestBuilderTest.java b/java/sdk/src/test/java/com/github/copilot/SessionRequestBuilderTest.java
index 0525786de..9d76d18ee 100644
--- a/java/sdk/src/test/java/com/github/copilot/SessionRequestBuilderTest.java
+++ b/java/sdk/src/test/java/com/github/copilot/SessionRequestBuilderTest.java
@@ -26,6 +26,7 @@
import com.github.copilot.rpc.ExitPlanModeResult;
import com.github.copilot.rpc.ExpConfigEntry;
import com.github.copilot.rpc.GitHubMcpToolConfig;
+import com.github.copilot.rpc.GitHubTokenProviderResult;
import com.github.copilot.rpc.LargeToolOutputConfig;
import com.github.copilot.rpc.MemoryConfiguration;
import com.github.copilot.rpc.ResumeSessionConfig;
@@ -56,6 +57,27 @@ void testBuildCreateRequestNullConfig() {
assertEquals("direct", request.getEnvValueMode(), "envValueMode should be 'direct' even for null config");
}
+ @Test
+ void testGitHubTokenProviderRegistrationWireFieldHasExactCasing() throws Exception {
+ var create = SessionRequestBuilder.buildCreateRequest(new SessionConfig(), "create-session");
+ create.setGitHubTokenProviderRegistrationId("create-registration");
+ var resume = SessionRequestBuilder.buildResumeRequest("resume-session", new ResumeSessionConfig());
+ resume.setGitHubTokenProviderRegistrationId("resume-registration");
+ var mapper = JsonRpcClient.getObjectMapper();
+
+ assertEquals("create-registration",
+ mapper.readTree(mapper.writeValueAsBytes(create)).path("gitHubTokenProviderRegistrationId").asText());
+ assertEquals("resume-registration",
+ mapper.readTree(mapper.writeValueAsBytes(resume)).path("gitHubTokenProviderRegistrationId").asText());
+ assertFalse(mapper.readTree(mapper.writeValueAsBytes(create)).has("gitHubToken"));
+ }
+
+ @Test
+ void testGitHubTokenProviderResultRedactsToken() {
+ var result = GitHubTokenProviderResult.token("do-not-print", 28_800);
+ assertFalse(result.toString().contains("do-not-print"));
+ }
+
@Test
void testBuildCreateRequestHooksNonNullButEmpty() {
// Hooks object exists but hasHooks() returns false
diff --git a/nodejs/README.md b/nodejs/README.md
index eec674ce4..93f9c3fa6 100644
--- a/nodejs/README.md
+++ b/nodejs/README.md
@@ -137,12 +137,25 @@ Create a new conversation session.
- `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
- `workingDirectory?: string` - Working directory for the session (default: runtime process cwd).
- `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
+- `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require a positive `expiresIn` value in seconds remaining when the callback completes; production tokens typically last eight hours. Cannot be combined with `gitHubToken`.
- `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
- `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `approveAll` approves requests when managed settings are disabled and throws when `enableManagedSettings` is true. Custom handlers can inspect `managedApprovalRequired` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.
- `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section.
- `onElicitationRequest?: ElicitationHandler` - Handler for elicitation requests dispatched by the server. Enables this client to present form-based UI dialogs on behalf of the agent or other session participants. See [Elicitation Requests](#elicitation-requests) section.
- `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
+```typescript
+const session = await client.createSession({
+ gitHubTokenProvider: async ({ host }) => ({
+ kind: "token",
+ accessToken: await acquireTokenForHost(host),
+ expiresIn: 8 * 60 * 60,
+ }),
+});
+```
+
+Initial acquisition runs during session creation or resume. Cancellation, provider errors, and invalid token responses reject that operation instead of falling back to ambient authentication. Idle sessions refresh only before their next credential-consuming operation; there is no background refresh timer.
+
##### `resumeSession(sessionId: string, config?: ResumeSessionConfig): Promise`
Resume an existing session. Returns the session with `workspacePath` populated if infinite sessions were enabled.
diff --git a/nodejs/src/client.ts b/nodejs/src/client.ts
index 1be2cbb94..9bed7e9e0 100644
--- a/nodejs/src/client.ts
+++ b/nodejs/src/client.ts
@@ -35,6 +35,8 @@ import {
} from "./generated/rpc.js";
import type {
GitHubTelemetryNotification,
+ GitHubTokenAcquireRequest,
+ GitHubTokenAcquireResult,
OpenCanvasInstance,
SessionUpdateOptionsParams,
} from "./generated/rpc.js";
@@ -58,6 +60,7 @@ import type {
ForegroundSessionInfo,
GetAuthStatusResponse,
BearerTokenProvider,
+ GitHubTokenProvider,
GetStatusResponse,
InternalRuntimeConnection,
RuntimeConnection,
@@ -524,6 +527,10 @@ export class CopilotClient {
private builtinPluginDirectories: string[] = [];
private onGitHubTelemetry?: (notification: GitHubTelemetryNotification) => void | Promise;
private clientGlobalHandlers: import("./generated/rpc.js").ClientGlobalApiHandlers = {};
+ private githubTokenProviders = new Map<
+ string,
+ { provider: GitHubTokenProvider; sessionId?: string; committed: boolean }
+ >();
/**
* Typed server-scoped RPC methods.
@@ -862,9 +869,65 @@ export class CopilotClient {
},
};
}
+ handlers.gitHubToken = {
+ getToken: (params) => this.acquireGitHubToken(params),
+ };
this.clientGlobalHandlers = handlers;
}
+ private async acquireGitHubToken(
+ params: GitHubTokenAcquireRequest
+ ): Promise {
+ const registration = this.githubTokenProviders.get(params.registrationId);
+ if (!registration) {
+ throw new Error(
+ `No GitHub token provider registered for registration ID "${params.registrationId}"`
+ );
+ }
+ return await registration.provider({
+ host: params.host,
+ sessionId: params.sessionId ?? registration.sessionId,
+ reason: params.reason,
+ });
+ }
+
+ private registerGitHubTokenProvider(
+ provider: GitHubTokenProvider | undefined,
+ sessionId?: string
+ ): string | undefined {
+ if (!provider) {
+ return undefined;
+ }
+ const registrationId = randomUUID();
+ this.githubTokenProviders.set(registrationId, { provider, sessionId, committed: false });
+ return registrationId;
+ }
+
+ private assignGitHubTokenProvider(registrationId: string | undefined, sessionId: string): void {
+ if (!registrationId) {
+ return;
+ }
+ const registration = this.githubTokenProviders.get(registrationId);
+ if (registration) {
+ registration.sessionId = sessionId;
+ }
+ }
+
+ private commitGitHubTokenProvider(sessionId: string, registrationId?: string): void {
+ for (const [candidateId, registration] of this.githubTokenProviders) {
+ if (registration.sessionId === sessionId && registration.committed) {
+ this.githubTokenProviders.delete(candidateId);
+ }
+ }
+ const registration = registrationId
+ ? this.githubTokenProviders.get(registrationId)
+ : undefined;
+ if (registration) {
+ registration.sessionId = sessionId;
+ registration.committed = true;
+ }
+ }
+
/**
* Starts the CLI server and establishes a connection.
*
@@ -1015,6 +1078,7 @@ export class CopilotClient {
session._markDisconnected();
}
this.sessions.clear();
+ this.githubTokenProviders.clear();
// Ask SDK-owned runtimes to flush and clean up before we tear down
// their transport/process. External runtimes may be shared, so only
@@ -1197,6 +1261,7 @@ export class CopilotClient {
session._markDisconnected();
}
this.sessions.clear();
+ this.githubTokenProviders.clear();
// Force close connection. Suppress writer failures first so teardown
// write rejections don't surface as unhandled rejections.
@@ -1444,6 +1509,9 @@ export class CopilotClient {
}
async createSession(config: SessionConfig): Promise {
+ if (config.gitHubToken !== undefined && config.gitHubTokenProvider !== undefined) {
+ throw new Error("gitHubToken and gitHubTokenProvider are mutually exclusive");
+ }
if (!this.connection) {
await this.start();
}
@@ -1463,6 +1531,11 @@ export class CopilotClient {
const callerSessionId = config.sessionId;
const useServerGeneratedId = config.cloud != null && callerSessionId == null;
const localSessionId = useServerGeneratedId ? undefined : (callerSessionId ?? randomUUID());
+ const toolFilterOptions = this.resolveToolFilterOptions(config);
+ const gitHubTokenProviderRegistrationId = this.registerGitHubTokenProvider(
+ config.gitHubTokenProvider,
+ localSessionId
+ );
// Strip non-serializable bearerTokenProvider callbacks from provider configs,
// replacing them with a wire flag; keep the callbacks for session-side
@@ -1491,6 +1564,13 @@ export class CopilotClient {
managedSettingsEnabled:
config.enableManagedSettings === true ||
config.managedSettings !== undefined,
+ onDisconnected:
+ gitHubTokenProviderRegistrationId === undefined
+ ? undefined
+ : () =>
+ this.githubTokenProviders.delete(
+ gitHubTokenProviderRegistrationId
+ ),
}
);
s.registerTools(config.tools);
@@ -1534,12 +1614,17 @@ export class CopilotClient {
// processing (e.g. sessionFs.writeFile for workspace metadata) can be
// routed to the correct handlers.
if (localSessionId !== undefined) {
- session = initializeSession(localSessionId);
- registeredId = localSessionId;
+ try {
+ session = initializeSession(localSessionId);
+ registeredId = localSessionId;
+ } catch (error) {
+ if (gitHubTokenProviderRegistrationId !== undefined) {
+ this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
+ }
+ throw error;
+ }
}
- const toolFilterOptions = this.resolveToolFilterOptions(config);
-
try {
const response = await this.connection!.sendRequest("session.create", {
...(await getTraceContext(this.onGetTraceContext)),
@@ -1628,6 +1713,7 @@ export class CopilotClient {
infiniteSessions: config.infiniteSessions,
memory: config.memory,
gitHubToken: config.gitHubToken,
+ gitHubTokenProviderRegistrationId,
remoteSession: config.remoteSession,
cloud: config.cloud,
expAssignments: config.expAssignments,
@@ -1658,6 +1744,7 @@ export class CopilotClient {
session = initializeSession(returnedSessionId);
registeredId = returnedSessionId;
}
+ this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
if (config.onMcpAuthRequest) {
await this.connection!.sendRequest("session.eventLog.registerInterest", {
sessionId: returnedSessionId,
@@ -1668,10 +1755,14 @@ export class CopilotClient {
session.setCapabilities(capabilities);
await this.updateSessionOptionsForMode(session, config);
+ this.commitGitHubTokenProvider(returnedSessionId, gitHubTokenProviderRegistrationId);
} catch (e) {
if (registeredId !== undefined) {
this.sessions.delete(registeredId);
}
+ if (gitHubTokenProviderRegistrationId !== undefined) {
+ this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
+ }
throw e;
}
@@ -1722,6 +1813,9 @@ export class CopilotClient {
factories?: FactoryHandle[],
extensionOptions?: ExtensionJoinOptions
): Promise {
+ if (config.gitHubToken !== undefined && config.gitHubTokenProvider !== undefined) {
+ throw new Error("gitHubToken and gitHubTokenProvider are mutually exclusive");
+ }
if (!this.connection) {
await this.start();
}
@@ -1787,6 +1881,15 @@ export class CopilotClient {
this.setupSessionFs(session, config);
const toolFilterOptions = this.resolveToolFilterOptions(config);
+ const gitHubTokenProviderRegistrationId = this.registerGitHubTokenProvider(
+ config.gitHubTokenProvider,
+ sessionId
+ );
+ if (gitHubTokenProviderRegistrationId !== undefined) {
+ session._setOnDisconnected(() =>
+ this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId)
+ );
+ }
try {
const response = await this.connection!.sendRequest("session.resume", {
@@ -1880,6 +1983,7 @@ export class CopilotClient {
disableResume: config.suppressResumeEvent,
continuePendingWork: config.continuePendingWork,
gitHubToken: config.gitHubToken,
+ gitHubTokenProviderRegistrationId,
remoteSession: config.remoteSession,
openCanvases: config.openCanvases,
expAssignments: config.expAssignments,
@@ -1927,8 +2031,12 @@ export class CopilotClient {
}
await this.updateSessionOptionsForMode(session, config);
+ this.commitGitHubTokenProvider(sessionId, gitHubTokenProviderRegistrationId);
} catch (e) {
this.sessions.delete(sessionId);
+ if (gitHubTokenProviderRegistrationId !== undefined) {
+ this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
+ }
throw e;
}
@@ -2172,8 +2280,9 @@ export class CopilotClient {
throw new Error(`Failed to delete session ${sessionId}: ${error || "Unknown error"}`);
}
- // Remove from local sessions map if present
+ const session = this.sessions.get(sessionId);
this.sessions.delete(sessionId);
+ session?._runOnDisconnected();
}
/**
@@ -2936,6 +3045,7 @@ export class CopilotClient {
this.connection.onClose(() => {
this.state = "disconnected";
+ this.githubTokenProviders.clear();
});
this.connection.onError((_error) => {
diff --git a/nodejs/src/index.ts b/nodejs/src/index.ts
index ae474eefe..bf7405c87 100644
--- a/nodejs/src/index.ts
+++ b/nodejs/src/index.ts
@@ -97,6 +97,11 @@ export type {
GitHubTelemetryNotification,
GitHubTelemetryEvent,
GitHubTelemetryClientInfo,
+ GitHubTokenAcquireReason,
+ GitHubTokenAcquireResult,
+ GitHubTokenProvider,
+ GitHubTokenProviderArgs,
+ GitHubTokenProviderResult,
InfiniteSessionConfig,
LargeToolOutputConfig,
MemoryConfiguration,
diff --git a/nodejs/src/session.ts b/nodejs/src/session.ts
index efe9fa3e9..d8b67133f 100644
--- a/nodejs/src/session.ts
+++ b/nodejs/src/session.ts
@@ -438,6 +438,7 @@ export class CopilotSession {
private _capabilities: SessionCapabilities = {};
private openCanvasInstances: OpenCanvasInstance[] = [];
private disconnected = false;
+ private onDisconnected?: () => void;
/** @internal Client session API handlers, populated by CopilotClient during create/resume. */
clientSessionApis: ClientSessionApiHandlers = {};
@@ -617,11 +618,16 @@ export class CopilotSession {
private connection: MessageConnection,
private _workspacePath?: string,
traceContextProvider?: TraceContextProvider,
- options?: { mcpAuthHandler?: McpAuthHandler; managedSettingsEnabled?: boolean }
+ options?: {
+ mcpAuthHandler?: McpAuthHandler;
+ managedSettingsEnabled?: boolean;
+ onDisconnected?: () => void;
+ }
) {
this.traceContextProvider = traceContextProvider;
this.mcpAuthHandler = options?.mcpAuthHandler;
this.managedSettingsEnabled = options?.managedSettingsEnabled === true;
+ this.onDisconnected = options?.onDisconnected;
}
/**
@@ -798,7 +804,11 @@ export class CopilotSession {
/** @internal */
_markDisconnected(): void {
+ if (this.disconnected) {
+ return;
+ }
this.disconnected = true;
+ this._runOnDisconnected();
this.eventHandlers.clear();
this.typedEventHandlers.clear();
this.toolHandlers.clear();
@@ -819,6 +829,17 @@ export class CopilotSession {
this.transformCallbacks?.clear();
}
+ /** @internal */
+ _runOnDisconnected(): void {
+ this.onDisconnected?.();
+ this.onDisconnected = undefined;
+ }
+
+ /** @internal */
+ _setOnDisconnected(callback: () => void): void {
+ this.onDisconnected = callback;
+ }
+
/**
* Subscribes to events from this session.
*
diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts
index 24d23d082..1fa376d86 100644
--- a/nodejs/src/types.ts
+++ b/nodejs/src/types.ts
@@ -21,6 +21,8 @@ import type {
import type { CopilotSession } from "./session.js";
import type { FactoryJsonSchema, JsonValue } from "./factory.js";
import type {
+ GitHubTokenAcquireRequest,
+ GitHubTokenAcquireResult,
GitHubTelemetryNotification,
ModelBillingTokenPrices,
OpenCanvasInstance,
@@ -31,10 +33,38 @@ import type { ToolSet } from "./toolSet.js";
export type { RemoteSessionMode } from "./generated/rpc.js";
export type { CurrentToolMetadata } from "./generated/rpc.js";
export type {
+ GitHubTokenAcquireReason,
+ GitHubTokenAcquireResult,
GitHubTelemetryNotification,
GitHubTelemetryEvent,
GitHubTelemetryClientInfo,
} from "./generated/rpc.js";
+
+/**
+ * Arguments passed to a session's {@link GitHubTokenProvider}.
+ *
+ * The callback registration identifier is intentionally kept inside the SDK.
+ */
+export type GitHubTokenProviderArgs = Pick<
+ GitHubTokenAcquireRequest,
+ "host" | "sessionId" | "reason"
+>;
+
+/** Tagged token or cancellation returned by a {@link GitHubTokenProvider}. */
+export type GitHubTokenProviderResult = GitHubTokenAcquireResult;
+
+/**
+ * Acquires a GitHub token for one session.
+ *
+ * A token result must include `expiresIn`: the positive number of seconds of
+ * remaining lifetime when the callback completes. Production GitHub tokens
+ * typically last eight hours. Initial cancellation, callback errors, and
+ * invalid token responses reject session creation or resume instead of falling
+ * back to ambient authentication.
+ */
+export type GitHubTokenProvider = (
+ args: GitHubTokenProviderArgs
+) => GitHubTokenProviderResult | Promise;
export type {
ModelBillingTokenPrices,
ModelBillingTokenPricesLongContext,
@@ -2712,6 +2742,16 @@ export interface SessionConfigBase {
*/
gitHubToken?: string;
+ /**
+ * Acquires short-lived GitHub credentials for this session on demand.
+ *
+ * Mutually exclusive with {@link SessionConfigBase.gitHubToken}. The
+ * callback receives the effective GitHub host, the session ID when known,
+ * and whether this is the initial acquisition or a refresh. Its opaque
+ * registration ID remains internal to the SDK.
+ */
+ gitHubTokenProvider?: GitHubTokenProvider;
+
/**
* Opt-in: when true, the runtime self-fetches enterprise managed settings
* (bypass-permissions policy) at session bootstrap using the session's
diff --git a/nodejs/test/github-token-provider.test.ts b/nodejs/test/github-token-provider.test.ts
new file mode 100644
index 000000000..2202f466a
--- /dev/null
+++ b/nodejs/test/github-token-provider.test.ts
@@ -0,0 +1,292 @@
+import { describe, expect, it, vi } from "vitest";
+import { CopilotClient, RuntimeConnection, type GitHubTokenProvider } from "../src/index.js";
+
+function createMockClient(
+ request: (method: string, params: Record) => Promise
+): CopilotClient {
+ const client = new CopilotClient({
+ connection: RuntimeConnection.forUri("localhost:1234"),
+ });
+ (client as unknown as { connection: unknown }).connection = {
+ sendRequest: request,
+ dispose: vi.fn(),
+ };
+ return client;
+}
+
+function getTokenHandler(client: CopilotClient) {
+ return (
+ client as unknown as {
+ clientGlobalHandlers: {
+ gitHubToken: {
+ getToken(params: {
+ registrationId: string;
+ host: string;
+ sessionId?: string;
+ reason: "initial" | "refresh";
+ }): Promise;
+ };
+ };
+ }
+ ).clientGlobalHandlers.gitHubToken.getToken;
+}
+
+describe("session GitHub token providers", () => {
+ it("rejects a static token and provider together", async () => {
+ const client = new CopilotClient({
+ connection: RuntimeConnection.forUri("localhost:1234"),
+ });
+
+ await expect(
+ client.createSession({
+ gitHubToken: "static",
+ gitHubTokenProvider: async () => ({
+ kind: "token",
+ accessToken: "dynamic",
+ expiresIn: 28_800,
+ }),
+ })
+ ).rejects.toThrow("gitHubToken and gitHubTokenProvider are mutually exclusive");
+ });
+
+ it("serializes only the opaque registration and maps token and cancellation results", async () => {
+ let createPayload: Record | undefined;
+ const request = vi.fn(async (method: string, params: Record) => {
+ if (method === "session.create") {
+ createPayload = params;
+ return { sessionId: params.sessionId };
+ }
+ throw new Error(`Unexpected method: ${method}`);
+ });
+ const observed: unknown[] = [];
+ const provider: GitHubTokenProvider = vi
+ .fn()
+ .mockImplementationOnce(async (args) => {
+ observed.push(args);
+ return {
+ kind: "token",
+ accessToken: "secret-token",
+ tokenType: "Bearer",
+ expiresIn: 28_800,
+ };
+ })
+ .mockImplementationOnce(async (args) => {
+ observed.push(args);
+ return { kind: "cancelled" };
+ });
+ const client = createMockClient(request);
+ const session = await client.createSession({
+ sessionId: "session-one",
+ gitHubTokenProvider: provider,
+ });
+
+ const registrationId = createPayload?.gitHubTokenProviderRegistrationId;
+ expect(registrationId).toMatch(
+ /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+ );
+ expect(createPayload).not.toHaveProperty("gitHubTokenProvider");
+ expect(createPayload?.gitHubToken).toBeUndefined();
+
+ const handler = getTokenHandler(client);
+ await expect(
+ handler({
+ registrationId: registrationId as string,
+ host: "github.example.com",
+ reason: "initial",
+ })
+ ).resolves.toEqual({
+ kind: "token",
+ accessToken: "secret-token",
+ tokenType: "Bearer",
+ expiresIn: 28_800,
+ });
+ await expect(
+ handler({
+ registrationId: registrationId as string,
+ host: "github.example.com",
+ sessionId: session.sessionId,
+ reason: "refresh",
+ })
+ ).resolves.toEqual({ kind: "cancelled" });
+ expect(observed).toEqual([
+ {
+ host: "github.example.com",
+ sessionId: "session-one",
+ reason: "initial",
+ },
+ {
+ host: "github.example.com",
+ sessionId: "session-one",
+ reason: "refresh",
+ },
+ ]);
+ });
+
+ it("preserves callback errors and rejects unknown registrations", async () => {
+ const client = createMockClient(async (_method, params) => ({
+ sessionId: params.sessionId,
+ }));
+ const failure = new Error("credential broker failed");
+ await client.createSession({
+ sessionId: "error-session",
+ gitHubTokenProvider: () => {
+ throw failure;
+ },
+ });
+ const registrationId = [
+ ...(
+ client as unknown as {
+ githubTokenProviders: Map;
+ }
+ ).githubTokenProviders.keys(),
+ ][0];
+ const handler = getTokenHandler(client);
+
+ await expect(
+ handler({
+ registrationId,
+ host: "github.com",
+ reason: "initial",
+ })
+ ).rejects.toBe(failure);
+ await expect(
+ handler({
+ registrationId: "unknown",
+ host: "github.com",
+ reason: "refresh",
+ })
+ ).rejects.toThrow("No GitHub token provider registered");
+ });
+
+ it("rolls back failed creation and cleans up on session and client close", async () => {
+ const failingClient = createMockClient(async () => {
+ throw new Error("create failed");
+ });
+ await expect(
+ failingClient.createSession({
+ gitHubTokenProvider: async () => ({ kind: "cancelled" }),
+ })
+ ).rejects.toThrow("create failed");
+ expect(
+ (
+ failingClient as unknown as {
+ githubTokenProviders: Map;
+ }
+ ).githubTokenProviders
+ ).toHaveLength(0);
+
+ const client = createMockClient(async (method, params) => {
+ if (method === "session.create") return { sessionId: params.sessionId };
+ if (method === "session.destroy") return {};
+ if (method === "session.delete") return { success: true };
+ throw new Error(`Unexpected method: ${method}`);
+ });
+ const first = await client.createSession({
+ sessionId: "first",
+ gitHubTokenProvider: async () => ({ kind: "cancelled" }),
+ });
+ await client.createSession({
+ sessionId: "second",
+ gitHubTokenProvider: async () => ({ kind: "cancelled" }),
+ });
+ const registrations = (
+ client as unknown as {
+ githubTokenProviders: Map;
+ }
+ ).githubTokenProviders;
+ expect(registrations).toHaveLength(2);
+
+ await first.disconnect();
+ expect(registrations).toHaveLength(1);
+ await client.deleteSession("second");
+ expect(registrations).toHaveLength(0);
+ await client.forceStop();
+ expect(registrations).toHaveLength(0);
+ });
+
+ it("rotates a resumed session only after resume succeeds", async () => {
+ const payloads: Record[] = [];
+ const client = createMockClient(async (method, params) => {
+ payloads.push(params);
+ if (method === "session.create" || method === "session.resume") {
+ return { sessionId: params.sessionId };
+ }
+ throw new Error(`Unexpected method: ${method}`);
+ });
+ const firstProvider = vi.fn(async () => ({ kind: "cancelled" as const }));
+ const secondProvider = vi.fn(async () => ({ kind: "cancelled" as const }));
+ await client.createSession({
+ sessionId: "resumed",
+ gitHubTokenProvider: firstProvider,
+ });
+ const firstRegistration = payloads[0].gitHubTokenProviderRegistrationId as string;
+
+ await client.resumeSession("resumed", {
+ gitHubTokenProvider: secondProvider,
+ });
+ const secondRegistration = payloads[1].gitHubTokenProviderRegistrationId as string;
+ const handler = getTokenHandler(client);
+
+ await expect(
+ handler({
+ registrationId: firstRegistration,
+ host: "github.com",
+ reason: "refresh",
+ })
+ ).rejects.toThrow("No GitHub token provider registered");
+ await expect(
+ handler({
+ registrationId: secondRegistration,
+ host: "github.com",
+ reason: "refresh",
+ })
+ ).resolves.toEqual({ kind: "cancelled" });
+ expect(secondProvider).toHaveBeenCalledOnce();
+ expect(firstProvider).not.toHaveBeenCalled();
+ });
+
+ it("does not retire a concurrent pending registration", async () => {
+ const resumeResolvers: Array<(value: { sessionId: string }) => void> = [];
+ const payloads: Record[] = [];
+ const client = createMockClient(async (method, params) => {
+ payloads.push(params);
+ if (method === "session.create") {
+ return { sessionId: params.sessionId };
+ }
+ if (method === "session.resume") {
+ return await new Promise<{ sessionId: string }>((resolve) => {
+ resumeResolvers.push(resolve);
+ });
+ }
+ throw new Error(`Unexpected method: ${method}`);
+ });
+ await client.createSession({
+ sessionId: "concurrent",
+ gitHubTokenProvider: async () => ({ kind: "cancelled" }),
+ });
+
+ const firstResume = client.resumeSession("concurrent", {
+ gitHubTokenProvider: async () => ({ kind: "cancelled" }),
+ });
+ const secondResume = client.resumeSession("concurrent", {
+ gitHubTokenProvider: async () => ({ kind: "cancelled" }),
+ });
+ await vi.waitFor(() => expect(resumeResolvers).toHaveLength(2));
+
+ resumeResolvers[0]({ sessionId: "concurrent" });
+ await firstResume;
+ const registrations = (
+ client as unknown as {
+ githubTokenProviders: Map;
+ }
+ ).githubTokenProviders;
+ expect(registrations).toHaveLength(2);
+
+ resumeResolvers[1]({ sessionId: "concurrent" });
+ await secondResume;
+ expect(registrations).toHaveLength(1);
+ expect(registrations.has(payloads[2].gitHubTokenProviderRegistrationId as string)).toBe(
+ true
+ );
+ });
+});
diff --git a/python/README.md b/python/README.md
index dc0a6a679..61608c16a 100644
--- a/python/README.md
+++ b/python/README.md
@@ -281,9 +281,25 @@ These are passed as keyword arguments to `create_session()`:
- `infinite_sessions` (InfiniteSessionConfig): Automatic context compaction configuration
- `working_directory` (str | None): Working directory for the session (default: runtime process working directory).
- `enable_session_store` (bool): Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
+- `github_token_provider` (callable): Acquires rotating, session-scoped GitHub tokens. Token results require a positive `expiresIn` value in seconds remaining when the callback completes; production tokens typically last eight hours. Cannot be combined with `github_token`.
- `on_permission_request` (callable): Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `PermissionHandler.approve_all` approves requests when managed settings are disabled and raises an error when `enable_managed_settings` is true. Custom handlers can inspect `managed_approval_required` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.
- `on_user_input_request` (callable): Handler for user input requests from the agent (enables ask_user tool). See [User Input Requests](#user-input-requests) section.
- `hooks` (SessionHooks): Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
+
+```python
+async def provide_github_token(args):
+ return {
+ "kind": "token",
+ "accessToken": await acquire_token_for_host(args["host"]),
+ "expiresIn": 8 * 60 * 60,
+ }
+
+
+session = await client.create_session(github_token_provider=provide_github_token)
+```
+
+Initial acquisition runs during session creation or resume. Cancellation, provider errors, and invalid token responses reject that operation instead of falling back to ambient authentication. Idle sessions refresh only before their next credential-consuming operation; there is no background refresh timer.
+
- `available_tools` / `excluded_tools` / `default_agent.excluded_tools` / custom-agent `tools`: MCP tools registered from `mcp_servers` are exposed to the runtime as `-`. For `available_tools` and `excluded_tools`, prefer `ToolSet().add_mcp("-")` or the raw `mcp:-` form. For custom-agent `tools` and `default_agent.excluded_tools`, use `-` directly.
**Session Lifecycle Methods:**
diff --git a/python/copilot/__init__.py b/python/copilot/__init__.py
index 8f30632e3..5f5bef88b 100644
--- a/python/copilot/__init__.py
+++ b/python/copilot/__init__.py
@@ -40,6 +40,11 @@
ExpFlagValue,
GetAuthStatusResponse,
GetStatusResponse,
+ GitHubTokenCancelledResult,
+ GitHubTokenProvider,
+ GitHubTokenProviderArgs,
+ GitHubTokenProviderResult,
+ GitHubTokenResult,
InProcessRuntimeConnection,
LogLevel,
ManagedSettings,
@@ -86,6 +91,9 @@
GitHubTelemetryClientInfo,
GitHubTelemetryEvent,
GitHubTelemetryNotification,
+ GitHubTokenAcquireReason,
+ GitHubTokenAcquireResult,
+ GitHubTokenAcquireResultKind,
ModelBillingTokenPrices,
ModelBillingTokenPricesLongContext,
PermissionDecisionContext,
@@ -267,6 +275,14 @@
"GitHubTelemetryClientInfo",
"GitHubTelemetryEvent",
"GitHubTelemetryNotification",
+ "GitHubTokenAcquireReason",
+ "GitHubTokenAcquireResult",
+ "GitHubTokenAcquireResultKind",
+ "GitHubTokenProvider",
+ "GitHubTokenProviderArgs",
+ "GitHubTokenProviderResult",
+ "GitHubTokenResult",
+ "GitHubTokenCancelledResult",
"InfiniteSessionConfig",
"InProcessRuntimeConnection",
"InputOptions",
diff --git a/python/copilot/client.py b/python/copilot/client.py
index ad4b0fe17..96d57c4d4 100644
--- a/python/copilot/client.py
+++ b/python/copilot/client.py
@@ -29,7 +29,7 @@
from dataclasses import dataclass, field
from datetime import UTC, datetime
from types import TracebackType
-from typing import Any, ClassVar, Literal, TypedDict, cast, overload
+from typing import Any, ClassVar, Literal, NotRequired, TypedDict, cast, overload
from ._diagnostics import log_timing
from ._ffi_runtime_host import FfiRuntimeHost
@@ -69,6 +69,9 @@
ClientGlobalApiHandlers,
ClientSessionApiHandlers,
GitHubTelemetryNotification,
+ GitHubTokenAcquireReason,
+ GitHubTokenAcquireRequest,
+ GitHubTokenAcquireResult,
ModelBillingTokenPrices,
ModelBillingTokenPricesLongContext, # noqa: F401
OpenCanvasInstance,
@@ -123,6 +126,50 @@
logger = logging.getLogger(__name__)
+
+class GitHubTokenProviderArgs(TypedDict):
+ """Arguments passed to a session-scoped :data:`GitHubTokenProvider`.
+
+ The opaque callback registration identifier is intentionally not exposed.
+ """
+
+ host: str
+ session_id: str | None
+ reason: GitHubTokenAcquireReason
+
+
+class GitHubTokenResult(TypedDict):
+ """A GitHub token returned by a session-scoped provider."""
+
+ kind: Literal["token"]
+ accessToken: str
+ expiresIn: int
+ tokenType: NotRequired[str]
+
+
+class GitHubTokenCancelledResult(TypedDict):
+ """An explicit cancellation returned by a session-scoped provider."""
+
+ kind: Literal["cancelled"]
+
+
+GitHubTokenProviderResult = GitHubTokenResult | GitHubTokenCancelledResult
+"""Result returned by a session-scoped GitHub token provider."""
+
+
+GitHubTokenProvider = Callable[
+ [GitHubTokenProviderArgs],
+ GitHubTokenProviderResult | Awaitable[GitHubTokenProviderResult],
+]
+"""Acquire a GitHub credential for one session.
+
+Token results require ``expiresIn`` to be the positive number of seconds of
+remaining lifetime when the callback completes. Production GitHub tokens
+typically last eight hours. Initial cancellation, callback errors, and invalid
+token responses reject session creation or resume instead of falling back to
+ambient authentication.
+"""
+
# ============================================================================
# Connection Types
# ============================================================================
@@ -633,6 +680,43 @@ async def event(self, params: GitHubTelemetryNotification) -> None:
logger.warning("Error handling gitHubTelemetry.event notification", exc_info=True)
+@dataclass
+class _GitHubTokenProviderRegistration:
+ provider: GitHubTokenProvider
+ session_id: str | None = None
+ committed: bool = False
+
+
+class _GitHubTokenProviderAdapter:
+ """Routes global GitHub token requests to opaque session registrations."""
+
+ def __init__(self, client: CopilotClient) -> None:
+ self._client = client
+
+ async def get_token(self, params: GitHubTokenAcquireRequest) -> GitHubTokenAcquireResult:
+ with self._client._github_token_providers_lock:
+ registration = self._client._github_token_providers.get(params.registration_id)
+ if registration is None:
+ raise JsonRpcError(
+ -32603,
+ "No GitHub token provider registered for registration ID "
+ f"{params.registration_id!r}",
+ )
+
+ result = registration.provider(
+ GitHubTokenProviderArgs(
+ host=params.host,
+ session_id=params.session_id or registration.session_id,
+ reason=params.reason,
+ )
+ )
+ if inspect.isawaitable(result):
+ result = await result
+ # The generated global-handler wrapper forwards callback results directly,
+ # so the public tagged dictionary is already in the expected wire shape.
+ return cast(GitHubTokenAcquireResult, result)
+
+
class _HooksAdapter:
"""Adapts session-scoped hook dispatch to the generated ``HooksHandler`` protocol.
@@ -1622,6 +1706,9 @@ def __init__(
self._state: _ConnectionState = "disconnected"
self._sessions: dict[str, CopilotSession] = {}
self._sessions_lock = threading.Lock()
+ self._github_token_providers: dict[str, _GitHubTokenProviderRegistration] = {}
+ self._github_token_providers_lock = threading.Lock()
+ self._github_token_provider_adapter = _GitHubTokenProviderAdapter(self)
self._models_cache: list[ModelInfo] | None = None
self._models_cache_lock = asyncio.Lock()
self._lifecycle_handlers: list[SessionLifecycleHandler] = []
@@ -1936,6 +2023,8 @@ async def stop(self) -> None:
errors.append(
StopError(message=f"Failed to disconnect session {session.session_id}: {e}")
)
+ with self._github_token_providers_lock:
+ self._github_token_providers.clear()
if (
self._rpc is not None
@@ -2052,6 +2141,8 @@ async def force_stop(self) -> None:
# Clear sessions immediately without trying to destroy them
with self._sessions_lock:
self._sessions.clear()
+ with self._github_token_providers_lock:
+ self._github_token_providers.clear()
# Close the transport first to signal the server immediately.
# For external servers (TCP), this closes the socket.
@@ -2169,6 +2260,7 @@ async def create_session(
on_auto_mode_switch_request: AutoModeSwitchHandler | None = None,
create_session_fs_handler: CreateSessionFsHandler | None = None,
github_token: str | None = None,
+ github_token_provider: GitHubTokenProvider | None = None,
remote_session: RemoteSessionMode | None = None,
cloud: CloudSessionOptions | None = None,
canvases: list[CanvasDeclaration] | None = None,
@@ -2344,6 +2436,11 @@ async def create_session(
May be combined with ``enable_managed_settings``. Requires a
runtime whose RPC schema includes ``managedSettings``. Sent on
the wire as ``managedSettings``.
+ github_token_provider: Callback that acquires a short-lived GitHub
+ credential for this session. Mutually exclusive with
+ ``github_token``. It receives the effective host, session ID
+ when assigned, and acquisition reason; the registration ID is
+ kept internal.
Returns:
A :class:`CopilotSession` instance for the new session.
@@ -2365,6 +2462,8 @@ async def create_session(
"""
if on_permission_request is not None and not callable(on_permission_request):
raise ValueError("on_permission_request must be callable when provided.")
+ if github_token is not None and github_token_provider is not None:
+ raise ValueError("github_token and github_token_provider are mutually exclusive")
if not self._client:
await self.start()
@@ -2666,6 +2765,11 @@ async def create_session(
)
if local_session_id is not None:
payload["sessionId"] = local_session_id
+ github_token_provider_registration_id = self._register_github_token_provider(
+ github_token_provider, local_session_id
+ )
+ if github_token_provider_registration_id is not None:
+ payload["gitHubTokenProviderRegistrationId"] = github_token_provider_registration_id
# Propagate W3C Trace Context to CLI if OpenTelemetry is active
trace_ctx = get_trace_context()
@@ -2686,6 +2790,13 @@ def _initialize_session(sid: str) -> CopilotSession:
workspace_path=None,
managed_settings_enabled=enable_managed_settings is True
or managed_settings is not None,
+ on_disconnect=(
+ None
+ if github_token_provider_registration_id is None
+ else lambda: self._unregister_github_token_provider(
+ github_token_provider_registration_id
+ )
+ ),
)
if self._session_fs_config:
if create_session_fs_handler is None:
@@ -2747,8 +2858,12 @@ def _initialize_session(sid: str) -> CopilotSession:
# processing (e.g. sessionFs.writeFile for workspace metadata) can be
# routed to the correct handlers.
if local_session_id is not None:
- session = _initialize_session(local_session_id)
- registered_session_id = local_session_id
+ try:
+ session = _initialize_session(local_session_id)
+ registered_session_id = local_session_id
+ except BaseException:
+ self._unregister_github_token_provider(github_token_provider_registration_id)
+ raise
try:
rpc_start = time.perf_counter()
@@ -2788,6 +2903,9 @@ def _register_inline(raw_response: Any) -> None:
f"session.create returned sessionId {response.get('sessionId')} "
f"but the caller requested {local_session_id}"
)
+ self._assign_github_token_provider(
+ github_token_provider_registration_id, session.session_id
+ )
if on_mcp_auth_request is not None:
await self._client.request(
"session.eventLog.registerInterest",
@@ -2800,6 +2918,7 @@ def _register_inline(raw_response: Any) -> None:
if registered_session_id is not None:
with self._sessions_lock:
self._sessions.pop(registered_session_id, None)
+ self._unregister_github_token_provider(github_token_provider_registration_id)
if not isinstance(exc, asyncio.CancelledError):
log_timing(
logger,
@@ -2819,6 +2938,9 @@ def _register_inline(raw_response: Any) -> None:
coauthor_enabled,
manage_schedule_enabled,
)
+ self._commit_github_token_provider(
+ session.session_id, github_token_provider_registration_id
+ )
log_timing(
logger,
@@ -2897,6 +3019,7 @@ async def resume_session(
on_auto_mode_switch_request: AutoModeSwitchHandler | None = None,
create_session_fs_handler: CreateSessionFsHandler | None = None,
github_token: str | None = None,
+ github_token_provider: GitHubTokenProvider | None = None,
remote_session: RemoteSessionMode | None = None,
continue_pending_work: bool | None = None,
canvases: list[CanvasDeclaration] | None = None,
@@ -3071,6 +3194,10 @@ async def resume_session(
injected layer, and omitting it clears that layer so warm and
cold resume behave identically. See :meth:`create_session`. Sent
on the wire as ``managedSettings``.
+ github_token_provider: Callback that acquires a short-lived GitHub
+ credential for this resumed session. Mutually exclusive with
+ ``github_token``. The new registration replaces the prior
+ provider only after resume succeeds.
Returns:
A :class:`CopilotSession` instance for the resumed session.
@@ -3094,6 +3221,8 @@ async def resume_session(
"""
if on_permission_request is not None and not callable(on_permission_request):
raise ValueError("on_permission_request must be callable when provided.")
+ if github_token is not None and github_token_provider is not None:
+ raise ValueError("github_token and github_token_provider are mutually exclusive")
if not self._client:
await self.start()
@@ -3415,6 +3544,16 @@ async def resume_session(
commands_count=len(commands or []),
has_hooks=hooks is not None,
)
+ github_token_provider_registration_id = self._register_github_token_provider(
+ github_token_provider, session_id
+ )
+ if github_token_provider_registration_id is not None:
+ payload["gitHubTokenProviderRegistrationId"] = github_token_provider_registration_id
+ session._set_disconnect_callback(
+ lambda: self._unregister_github_token_provider(
+ github_token_provider_registration_id
+ )
+ )
try:
rpc_start = time.perf_counter()
@@ -3442,6 +3581,7 @@ async def resume_session(
except BaseException as exc:
with self._sessions_lock:
self._sessions.pop(session_id, None)
+ self._unregister_github_token_provider(github_token_provider_registration_id)
if not isinstance(exc, asyncio.CancelledError):
log_timing(
logger,
@@ -3461,6 +3601,7 @@ async def resume_session(
coauthor_enabled,
manage_schedule_enabled,
)
+ self._commit_github_token_provider(session_id, github_token_provider_registration_id)
log_timing(
logger,
@@ -3680,8 +3821,9 @@ async def delete_session(self, session_id: str) -> None:
# Remove from local sessions map if present
with self._sessions_lock:
- if session_id in self._sessions:
- del self._sessions[session_id]
+ session = self._sessions.pop(session_id, None)
+ if session is not None:
+ session._run_disconnect_callback()
async def get_last_session_id(self) -> str | None:
"""
@@ -4350,7 +4492,7 @@ async def _connect_via_stdio(self) -> None:
# Create JSON-RPC client with the process
self._client = JsonRpcClient(self._process)
- self._client.on_close = lambda: setattr(self, "_state", "disconnected")
+ self._client.on_close = self._handle_connection_close
self._rpc = ServerRpc(self._client)
# Set up notification handler for session events
@@ -4471,7 +4613,7 @@ def wait(self, timeout=None):
self._process = SocketWrapper(sock_file, sock)
self._client = JsonRpcClient(self._process)
- self._client.on_close = lambda: setattr(self, "_state", "disconnected")
+ self._client.on_close = self._handle_connection_close
self._rpc = ServerRpc(self._client)
# Set up notification handler for session events
@@ -4592,9 +4734,56 @@ def _register_client_global_handlers(self) -> None:
hooks=_HooksAdapter(self._get_session),
llm_inference=llm_inference_adapter,
git_hub_telemetry=github_telemetry_adapter,
+ git_hub_token=self._github_token_provider_adapter,
),
)
+ def _register_github_token_provider(
+ self, provider: GitHubTokenProvider | None, session_id: str | None
+ ) -> str | None:
+ if provider is None:
+ return None
+ registration_id = str(uuid.uuid4())
+ with self._github_token_providers_lock:
+ self._github_token_providers[registration_id] = _GitHubTokenProviderRegistration(
+ provider, session_id
+ )
+ return registration_id
+
+ def _handle_connection_close(self) -> None:
+ self._state = "disconnected"
+ with self._github_token_providers_lock:
+ self._github_token_providers.clear()
+
+ def _assign_github_token_provider(self, registration_id: str | None, session_id: str) -> None:
+ if registration_id is None:
+ return
+ with self._github_token_providers_lock:
+ registration = self._github_token_providers.get(registration_id)
+ if registration is not None:
+ registration.session_id = session_id
+
+ def _unregister_github_token_provider(self, registration_id: str | None) -> None:
+ if registration_id is None:
+ return
+ with self._github_token_providers_lock:
+ self._github_token_providers.pop(registration_id, None)
+
+ def _commit_github_token_provider(self, session_id: str, registration_id: str | None) -> None:
+ with self._github_token_providers_lock:
+ stale = [
+ candidate_id
+ for candidate_id, registration in self._github_token_providers.items()
+ if registration.session_id == session_id and registration.committed
+ ]
+ for candidate_id in stale:
+ self._github_token_providers.pop(candidate_id, None)
+ if registration_id is not None:
+ registration = self._github_token_providers.get(registration_id)
+ if registration is not None:
+ registration.session_id = session_id
+ registration.committed = True
+
def _get_session(self, session_id: str) -> CopilotSession | None:
with self._sessions_lock:
return self._sessions.get(session_id)
diff --git a/python/copilot/session.py b/python/copilot/session.py
index 21c74bcaf..b3d8aa45c 100644
--- a/python/copilot/session.py
+++ b/python/copilot/session.py
@@ -1548,6 +1548,7 @@ def __init__(
client: Any,
workspace_path: os.PathLike[str] | str | None = None,
managed_settings_enabled: bool = False,
+ on_disconnect: Callable[[], None] | None = None,
):
"""
Initialize a new CopilotSession.
@@ -1600,6 +1601,17 @@ def __init__(
self._open_canvases_lock = threading.Lock()
self._rpc: SessionRpc | None = None
self._destroyed = False
+ self._on_disconnect = on_disconnect
+
+ def _set_disconnect_callback(self, callback: Callable[[], None]) -> None:
+ """Set the client-owned cleanup callback before the session becomes active."""
+ self._on_disconnect = callback
+
+ def _run_disconnect_callback(self) -> None:
+ callback = self._on_disconnect
+ self._on_disconnect = None
+ if callback is not None:
+ callback()
@property
def rpc(self) -> SessionRpc:
@@ -2973,6 +2985,7 @@ async def disconnect(self) -> None:
try:
await self._client.request("session.destroy", {"sessionId": self.session_id})
finally:
+ self._run_disconnect_callback()
# Clear handlers even if the request fails.
with self._event_handlers_lock:
self._event_handlers.clear()
diff --git a/python/test_github_token_provider.py b/python/test_github_token_provider.py
new file mode 100644
index 000000000..5b203f3e3
--- /dev/null
+++ b/python/test_github_token_provider.py
@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+import pytest
+
+from copilot import (
+ CopilotClient,
+ GitHubTokenAcquireReason,
+ RuntimeConnection,
+)
+from copilot._jsonrpc import JsonRpcClient, JsonRpcError
+from copilot.rpc import GitHubTokenAcquireRequest
+
+
+class FakeJsonRpcClient:
+ def __init__(self, *, fail_method: str | None = None) -> None:
+ self.fail_method = fail_method
+ self.requests: list[tuple[str, dict[str, Any]]] = []
+ self.request_handlers: dict[str, Any] = {}
+ self.notification_method_handlers: dict[str, Any] = {}
+
+ async def request(self, method: str, params: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+ self.requests.append((method, params))
+ if method == self.fail_method:
+ raise RuntimeError(f"{method} failed")
+ if method in {"session.create", "session.resume"}:
+ response = {"sessionId": params["sessionId"]}
+ callback = kwargs.get("on_response_inline")
+ if callback is not None:
+ callback(response)
+ return response
+ if method == "session.destroy":
+ return {}
+ if method == "session.delete":
+ return {"success": True}
+ raise RuntimeError(f"Unexpected method: {method}")
+
+ async def stop(self) -> None:
+ pass
+
+ def set_request_handler(self, method: str, handler: Any) -> None:
+ self.request_handlers[method] = handler
+
+ def set_notification_method_handler(self, method: str, handler: Any) -> None:
+ self.notification_method_handlers[method] = handler
+
+
+class ConcurrentResumeJsonRpcClient(FakeJsonRpcClient):
+ def __init__(self) -> None:
+ super().__init__()
+ self.resume_responses: list[asyncio.Future[dict[str, Any]]] = []
+
+ async def request(self, method: str, params: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+ self.requests.append((method, params))
+ if method == "session.create":
+ response = {"sessionId": params["sessionId"]}
+ callback = kwargs.get("on_response_inline")
+ if callback is not None:
+ callback(response)
+ return response
+ if method == "session.resume":
+ response = asyncio.get_running_loop().create_future()
+ self.resume_responses.append(response)
+ return await response
+ raise RuntimeError(f"Unexpected method: {method}")
+
+
+def make_client(fake: FakeJsonRpcClient) -> CopilotClient:
+ client = CopilotClient(connection=RuntimeConnection.for_uri("localhost:1234"))
+ client._client = cast(JsonRpcClient, fake)
+ return client
+
+
+class TestGitHubTokenProvider:
+ async def test_mutual_exclusion(self) -> None:
+ client = CopilotClient(connection=RuntimeConnection.for_uri("localhost:1234"))
+
+ with pytest.raises(
+ ValueError, match="github_token and github_token_provider are mutually exclusive"
+ ):
+ await client.create_session(
+ github_token="static",
+ github_token_provider=lambda _: {"kind": "cancelled"},
+ )
+
+ async def test_wire_mapping_token_and_cancelled(self) -> None:
+ fake = FakeJsonRpcClient()
+ client = make_client(fake)
+ observed: list[dict[str, Any]] = []
+
+ async def provider(args):
+ observed.append(dict(args))
+ if len(observed) == 1:
+ return {
+ "kind": "token",
+ "accessToken": "secret-token",
+ "tokenType": "Bearer",
+ "expiresIn": 28_800,
+ }
+ return {"kind": "cancelled"}
+
+ await client.create_session(
+ session_id="python-session",
+ github_token_provider=provider,
+ )
+ create_payload = fake.requests[0][1]
+ registration_id = create_payload["gitHubTokenProviderRegistrationId"]
+ assert "github_token_provider" not in create_payload
+ assert "gitHubToken" not in create_payload
+ client._register_client_global_handlers()
+ get_token = fake.request_handlers["gitHubToken.getToken"]
+
+ token = await get_token(
+ {
+ "registrationId": registration_id,
+ "host": "github.example.com",
+ "reason": "initial",
+ }
+ )
+ cancelled = await get_token(
+ {
+ "registrationId": registration_id,
+ "host": "github.example.com",
+ "reason": "refresh",
+ "sessionId": "python-session",
+ }
+ )
+
+ assert token == {
+ "kind": "token",
+ "accessToken": "secret-token",
+ "tokenType": "Bearer",
+ "expiresIn": 28_800,
+ }
+ assert cancelled == {"kind": "cancelled"}
+ assert observed == [
+ {
+ "host": "github.example.com",
+ "session_id": "python-session",
+ "reason": GitHubTokenAcquireReason.INITIAL,
+ },
+ {
+ "host": "github.example.com",
+ "session_id": "python-session",
+ "reason": GitHubTokenAcquireReason.REFRESH,
+ },
+ ]
+
+ async def test_callback_and_unknown_registration_errors(self) -> None:
+ fake = FakeJsonRpcClient()
+ client = make_client(fake)
+ failure = RuntimeError("credential broker failed")
+
+ def provider(_args):
+ raise failure
+
+ await client.create_session(
+ session_id="error-session",
+ github_token_provider=provider,
+ )
+ registration_id = fake.requests[0][1]["gitHubTokenProviderRegistrationId"]
+
+ with pytest.raises(RuntimeError, match="credential broker failed") as exc:
+ await client._github_token_provider_adapter.get_token(
+ GitHubTokenAcquireRequest(
+ registration_id=registration_id,
+ host="github.com",
+ reason=GitHubTokenAcquireReason.INITIAL,
+ )
+ )
+ assert exc.value is failure
+
+ with pytest.raises(JsonRpcError, match="No GitHub token provider registered"):
+ await client._github_token_provider_adapter.get_token(
+ GitHubTokenAcquireRequest(
+ registration_id="unknown",
+ host="github.com",
+ reason=GitHubTokenAcquireReason.REFRESH,
+ )
+ )
+
+ async def test_failure_session_close_and_client_close_cleanup(self) -> None:
+ failing = make_client(FakeJsonRpcClient(fail_method="session.create"))
+ with pytest.raises(RuntimeError, match="session.create failed"):
+ await failing.create_session(github_token_provider=lambda _: {"kind": "cancelled"})
+ assert failing._github_token_providers == {}
+
+ fake = FakeJsonRpcClient()
+ client = make_client(fake)
+ first = await client.create_session(
+ session_id="first",
+ github_token_provider=lambda _: {"kind": "cancelled"},
+ )
+ await client.create_session(
+ session_id="second",
+ github_token_provider=lambda _: {"kind": "cancelled"},
+ )
+ assert len(client._github_token_providers) == 2
+
+ await first.disconnect()
+ assert len(client._github_token_providers) == 1
+ await client.delete_session("second")
+ assert client._github_token_providers == {}
+ await client.force_stop()
+ assert client._github_token_providers == {}
+
+ async def test_resume_rotates_provider(self) -> None:
+ fake = FakeJsonRpcClient()
+ client = make_client(fake)
+ calls: list[str] = []
+
+ await client.create_session(
+ session_id="resumed",
+ github_token_provider=lambda _: calls.append("first") or {"kind": "cancelled"},
+ )
+ first_registration = fake.requests[0][1]["gitHubTokenProviderRegistrationId"]
+ await client.resume_session(
+ "resumed",
+ github_token_provider=lambda _: calls.append("second") or {"kind": "cancelled"},
+ )
+ second_registration = fake.requests[1][1]["gitHubTokenProviderRegistrationId"]
+
+ with pytest.raises(JsonRpcError):
+ await client._github_token_provider_adapter.get_token(
+ GitHubTokenAcquireRequest(
+ registration_id=first_registration,
+ host="github.com",
+ reason=GitHubTokenAcquireReason.REFRESH,
+ )
+ )
+ assert await client._github_token_provider_adapter.get_token(
+ GitHubTokenAcquireRequest(
+ registration_id=second_registration,
+ host="github.com",
+ reason=GitHubTokenAcquireReason.REFRESH,
+ )
+ ) == {"kind": "cancelled"}
+ assert calls == ["second"]
+
+ async def test_concurrent_resume_keeps_pending_registration(self) -> None:
+ fake = ConcurrentResumeJsonRpcClient()
+ client = make_client(fake)
+ await client.create_session(
+ session_id="concurrent",
+ github_token_provider=lambda _: {"kind": "cancelled"},
+ )
+
+ first_resume = asyncio.create_task(
+ client.resume_session(
+ "concurrent",
+ github_token_provider=lambda _: {"kind": "cancelled"},
+ )
+ )
+ second_resume = asyncio.create_task(
+ client.resume_session(
+ "concurrent",
+ github_token_provider=lambda _: {"kind": "cancelled"},
+ )
+ )
+ while len(fake.resume_responses) < 2:
+ await asyncio.sleep(0)
+
+ fake.resume_responses[0].set_result({"sessionId": "concurrent"})
+ await first_resume
+ assert len(client._github_token_providers) == 2
+
+ fake.resume_responses[1].set_result({"sessionId": "concurrent"})
+ await second_resume
+ assert len(client._github_token_providers) == 1
+ second_registration = fake.requests[2][1]["gitHubTokenProviderRegistrationId"]
+ assert second_registration in client._github_token_providers
diff --git a/rust/README.md b/rust/README.md
index 29fe67355..323d525d3 100644
--- a/rust/README.md
+++ b/rust/README.md
@@ -274,6 +274,34 @@ let config = SessionConfig {
let session = client.create_session(config).await?;
```
+For rotating per-session GitHub credentials, install a `GitHubTokenProvider`
+instead of setting `github_token`:
+
+```rust,ignore
+use github_copilot_sdk::{
+ GitHubToken, GitHubTokenProviderArgs, GitHubTokenProviderResult, SessionConfig,
+};
+
+let provider = Arc::new(|args: GitHubTokenProviderArgs| async move {
+ let access_token = acquire_for_host(&args.host).await?;
+ Ok(GitHubTokenProviderResult::Token(GitHubToken::new(
+ access_token,
+ 8 * 60 * 60,
+ )))
+});
+let config = SessionConfig::default().with_github_token_provider(provider);
+```
+
+The remaining lifetime is required and must be positive when the callback
+completes; production GitHub tokens typically last eight hours. Static
+`github_token` and a provider are mutually exclusive. The same provider API is
+available on `ResumeSessionConfig`.
+
+Initial acquisition runs during session creation or resume. Cancellation,
+provider errors, and invalid token responses reject that operation instead of
+falling back to ambient authentication. Idle sessions refresh only before their
+next credential-consuming operation; there is no background refresh timer.
+
### Session Hooks
Hooks intercept CLI behavior at lifecycle points — tool use, prompt submission, session start/end, and errors. Install a `SessionHooks` impl with [`SessionConfig::with_hooks`] — the SDK auto-enables `hooks` in `SessionConfig` when one is set.
diff --git a/rust/src/errors.rs b/rust/src/errors.rs
index 6e05bbfae..70f4c14ff 100644
--- a/rust/src/errors.rs
+++ b/rust/src/errors.rs
@@ -218,6 +218,8 @@ pub enum ErrorKind {
},
/// Invalid combination of options or configuration.
InvalidConfig,
+ /// A session-scoped GitHub token provider failed or returned invalid data.
+ GitHubTokenProvider,
}
impl fmt::Display for ErrorKind {
@@ -238,6 +240,7 @@ impl fmt::Display for ErrorKind {
write!(f, "binary not found: {name}")
}
ErrorKind::InvalidConfig => write!(f, "invalid configuration"),
+ ErrorKind::GitHubTokenProvider => write!(f, "GitHub token provider error"),
}
}
}
diff --git a/rust/src/github_token.rs b/rust/src/github_token.rs
new file mode 100644
index 000000000..c5eaa63ad
--- /dev/null
+++ b/rust/src/github_token.rs
@@ -0,0 +1,378 @@
+//! Session-scoped GitHub token provider callbacks.
+
+use std::collections::HashMap;
+use std::future::Future;
+use std::sync::{Arc, OnceLock, Weak};
+
+use async_trait::async_trait;
+use parking_lot::Mutex;
+use serde_json::Value;
+
+use crate::generated::api_types::{
+ GitHubTokenAcquireReason, GitHubTokenAcquireRequest, GitHubTokenAcquireResult,
+ GitHubTokenAcquireResultCancelled, GitHubTokenAcquireResultToken,
+};
+use crate::{Client, ClientInner, JsonRpcError, JsonRpcRequest, JsonRpcResponse, error_codes};
+
+/// Why the runtime is requesting a GitHub token.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GitHubTokenRequestReason {
+ /// The session needs its initial token.
+ Initial,
+ /// The session needs a refreshed token.
+ Refresh,
+}
+
+/// Context supplied when the runtime needs a GitHub token for a session.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GitHubTokenProviderArgs {
+ /// Effective GitHub host for which a token is required.
+ pub host: String,
+ /// Session receiving the token, when the runtime has assigned its ID.
+ pub session_id: Option,
+ /// Whether this is the initial token acquisition or a refresh.
+ pub reason: GitHubTokenRequestReason,
+}
+
+/// A GitHub access token returned by a session token provider.
+///
+/// `expires_in_seconds` is the positive remaining lifetime when the callback
+/// completes. Production GitHub tokens typically last eight hours.
+pub struct GitHubToken {
+ access_token: String,
+ expires_in_seconds: i64,
+ token_type: Option,
+}
+
+impl GitHubToken {
+ /// Construct a token response with its remaining lifetime in seconds.
+ pub fn new(access_token: impl Into, expires_in_seconds: i64) -> Self {
+ Self {
+ access_token: access_token.into(),
+ expires_in_seconds,
+ token_type: None,
+ }
+ }
+
+ /// Override the OAuth token type. The runtime defaults to `bearer` when unset.
+ pub fn with_token_type(mut self, token_type: impl Into) -> Self {
+ self.token_type = Some(token_type.into());
+ self
+ }
+
+ fn into_wire(self) -> GitHubTokenAcquireResultToken {
+ GitHubTokenAcquireResultToken {
+ access_token: self.access_token,
+ expires_in: self.expires_in_seconds,
+ kind: Default::default(),
+ token_type: self.token_type,
+ }
+ }
+}
+
+impl std::fmt::Debug for GitHubToken {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("GitHubToken")
+ .field("access_token", &"")
+ .field("expires_in_seconds", &self.expires_in_seconds)
+ .field("token_type", &self.token_type)
+ .finish()
+ }
+}
+
+/// Result of acquiring a session-scoped GitHub token.
+pub enum GitHubTokenProviderResult {
+ /// A token was acquired.
+ Token(GitHubToken),
+ /// The host cancelled acquisition.
+ Cancelled,
+}
+
+impl std::fmt::Debug for GitHubTokenProviderResult {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ Self::Token(token) => f.debug_tuple("Token").field(token).finish(),
+ Self::Cancelled => f.write_str("Cancelled"),
+ }
+ }
+}
+
+/// Async callback used to acquire GitHub tokens for one session.
+#[async_trait]
+pub trait GitHubTokenProvider: Send + Sync {
+ /// Acquire a token or explicitly cancel the request.
+ ///
+ /// Initial cancellation, errors, and invalid token responses reject session
+ /// creation or resume instead of falling back to ambient authentication.
+ async fn get_token(
+ &self,
+ args: GitHubTokenProviderArgs,
+ ) -> Result;
+}
+
+#[async_trait]
+impl GitHubTokenProvider for F
+where
+ F: Fn(GitHubTokenProviderArgs) -> Fut + Send + Sync,
+ Fut: Future