Sync Copilot SDK docs (auto-generated) (#63408)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: sunbrye <sunbrye@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 860ffa15-aef4-4655-a9cb-f4e04cc36886

Author: 4 people

assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png

@@ -215,6 +215,133 @@ const client = new CopilotClient({
 
 For more information, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/github-oauth).
 
+## Rotating session-scoped GitHub tokens
+
+For multi-user services and integrations, set a token provider on each session instead of storing one long-lived token. The runtime calls the provider for the effective GitHub host and identifies the request as `initial` or `refresh`. The session ID is absent only when a cloud session has not received its ID yet.
+
+Return a tagged token result or an explicit cancellation. Every token result must include `expiresIn`: the positive number of seconds remaining when the callback completes. Production GitHub tokens typically last eight hours, so `8 * 60 * 60` is a common value. Do not set both the static per-session token and the provider.
+
+{% codetabs %}
+{% codetab typescript %}
+
+<!-- docs-validate: skip -->
+
+```typescript
+const session = await client.createSession({
+    gitHubTokenProvider: async ({ host, sessionId, reason }) => {
+        const token = await acquireGitHubToken({ host, sessionId, reason });
+        return {
+            kind: "token",
+            accessToken: token.value,
+            expiresIn: token.secondsRemaining,
+        };
+    },
+});
+```
+
+{% endcodetab %}
+{% codetab python %}
+
+<!-- docs-validate: skip -->
+
+```python
+async def provide_github_token(args):
+    token = await acquire_github_token(
+        host=args["host"],
+        session_id=args["session_id"],
+        reason=args["reason"],
+    )
+    return {
+        "kind": "token",
+        "accessToken": token.value,
+        "expiresIn": token.seconds_remaining,
+    }
+
+
+session = await client.create_session(github_token_provider=provide_github_token)
+```
+
+{% endcodetab %}
+{% codetab go %}
+
+<!-- docs-validate: skip -->
+
+```golang
+session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+	GitHubTokenProvider: func(args copilot.GitHubTokenProviderArgs) (*copilot.GitHubTokenProviderResult, error) {
+		token, secondsRemaining, err := acquireGitHubToken(args.Host, args.SessionID, args.Reason)
+		if err != nil {
+			return nil, err
+		}
+		return copilot.GitHubTokenResult(&copilot.GitHubToken{
+			AccessToken: token,
+			ExpiresIn:   secondsRemaining,
+		}), nil
+	},
+})
+```
+
+{% endcodetab %}
+{% codetab dotnet %}
+
+<!-- docs-validate: skip -->
+
+```csharp
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+    GitHubTokenProvider = async args =>
+    {
+        var token = await AcquireGitHubTokenAsync(args.Host, args.SessionId, args.Reason);
+        return GitHubTokenProviderResult.FromToken(new GitHubToken
+        {
+            AccessToken = token.Value,
+            ExpiresIn = token.SecondsRemaining,
+        });
+    },
+});
+```
+
+{% endcodetab %}
+{% codetab java %}
+
+<!-- docs-validate: skip -->
+
+```java
+var session = client.createSession(new SessionConfig()
+    .setGitHubTokenProvider(args ->
+        acquireGitHubToken(args.host(), args.sessionId(), args.reason())
+            .thenApply(token -> GitHubTokenProviderResult.token(
+                token.value(), token.secondsRemaining())))
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+).get();
+```
+
+{% endcodetab %}
+{% codetab rust %}
+
+<!-- docs-validate: skip -->
+
+```rust
+let provider = Arc::new(|args: GitHubTokenProviderArgs| async move {
+    let token = acquire_github_token(&args.host, args.session_id.as_ref(), args.reason).await?;
+    Ok(GitHubTokenProviderResult::Token(GitHubToken::new(
+        token.value,
+        token.seconds_remaining,
+    )))
+});
+
+let session = client
+    .create_session(SessionConfig::default().with_github_token_provider(provider))
+    .await?;
+```
+
+{% endcodetab %}
+{% endcodetabs %}
+
+The runtime performs the `initial` acquisition as part of session creation or resume. A cancelled acquisition, provider error, invalid response, or token without a stable account identity rejects the create or resume operation. The runtime does not fall back to ambient authentication.
+
+After the session is established, the runtime performs async preflight before each credential-consuming operation. It requests a `refresh` when the current token has one hour or less remaining. Idle sessions are not refreshed until their next credential-consuming operation. The runtime does not use background timers, rejection-driven replay, 401/403 challenge propagation, or upscope for this callback.
+
 ## Environment variables
 
 For automation, CI/CD pipelines, and server-to-server scenarios, you can authenticate using environment variables.

assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png

@@ -234,8 +234,8 @@ Anthropic models always use the Anthropic Messages API regardless of this settin
 
 **Azure (`type: "azure"`)**
 * Use for native Azure OpenAI endpoints
-* `baseUrl` should be just the host (e.g., `https://my-resource.openai.azure.com`)
-* Do NOT include `/openai/v1` in the URL—the SDK handles path construction
+* `baseUrl` / `base_url` accepts a resource host or a full project URL, such as `https://<host>/api/projects/hosted-agents-ncus`, with or without a trailing slash.
+* The runtime preserves the project prefix when constructing Azure API paths. For `wireApi: "responses"` with `azure.apiVersion` omitted, the project URL above produces `https://<host>/api/projects/hosted-agents-ncus/openai/v1/responses`. Project URLs require an updated Copilot CLI runtime.
 
 **Anthropic (`type: "anthropic"`)**
 * For direct Anthropic API access
@@ -260,7 +260,7 @@ Use `type: "azure"` for endpoints at `*.openai.azure.com`:
 ```typescript
 provider: {
     type: "azure",
-    baseUrl: "https://my-resource.openai.azure.com",  // Just the host
+    baseUrl: "https://my-resource.openai.azure.com",  // Resource host or full project URL
     apiKey: process.env.AZURE_OPENAI_KEY,
     azure: {
         apiVersion: "2024-10-21",

assets/images/help/copilot/copilot-sdk/setup-in-process-runtime-diagram-0.png

@@ -0,0 +1,157 @@
+---
+title: Client info
+shortTitle: Client info
+intro: >-
+  Client info identifies the application using the Copilot SDK and, when
+  applicable, a specific integration within it. An integration is an
+  identifiable sub-part of the application through which the SDK is used, such
+  as an extension or plugin. Set the optional `clientInfo` client option to
+  attribute runtime telemetry for that connection to your application instead of
+  the runtime's own build.
+versions:
+  fpt: '*'
+  ghec: '*'
+contentType: how-tos
+---
+
+<!-- markdownlint-disable GHD046 GHD005 -->
+<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->
+
+## When to set client info
+
+Set client info when your SDK application represents a distinct product, service, or integration whose runtime activity should be attributed consistently.
+
+Leave client info unset for scripts, one-off tools, and jobs that do not represent a distinct application. The runtime then keeps its default attribution.
+
+Client info has four optional string fields. Set the fields you know and omit the rest. The SDK includes client info in the `server.connect` handshake only when at least one field has a non-empty value.
+
+| Field | Example | Meaning |
+|---|---|---|
+| `applicationName` | `"vscode"` | Name of the application using the SDK |
+| `applicationVersion` | `"1.124.2"` | Version of the application using the SDK |
+| `integrationName` | `"copilot-chat"` | Name of the extension, plugin, or other application sub-part using the SDK |
+| `integrationVersion` | `"0.54.0"` | Version of that extension, plugin, or application sub-part |
+
+For a standalone application without a distinct integration, set only the application fields. For example, a developer portal could set `applicationName` to `"acme-developer-portal"` and `applicationVersion` to `"2.4.0"`, leaving both integration fields unset.
+
+The SDK sends client info once when it establishes the connection. The identity applies for the lifetime of that connection.
+
+## Configure client info
+
+Pass client info when you create the client:
+
+{% codetabs %}
+{% codetab typescript %}
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient({
+  clientInfo: {
+    applicationName: "vscode",
+    applicationVersion: "1.124.2",
+    integrationName: "copilot-chat",
+    integrationVersion: "0.54.0",
+  },
+});
+
+await client.start();
+```
+
+{% endcodetab %}
+{% codetab python %}
+
+<!-- docs-validate: wrap-async -->
+
+```python
+from copilot import CopilotClient
+
+client = CopilotClient(
+    client_info={
+        "application_name": "vscode",
+        "application_version": "1.124.2",
+        "integration_name": "copilot-chat",
+        "integration_version": "0.54.0",
+    },
+)
+await client.start()
+```
+
+{% endcodetab %}
+{% codetab go %}
+
+```golang
+client := copilot.NewClient(&copilot.ClientOptions{
+    ClientInfo: &copilot.ClientInfo{
+        ApplicationName:    "vscode",
+        ApplicationVersion: "1.124.2",
+        IntegrationName:    "copilot-chat",
+        IntegrationVersion: "0.54.0",
+    },
+})
+if err := client.Start(ctx); err != nil {
+    return err
+}
+```
+
+{% endcodetab %}
+{% codetab dotnet %}
+
+```csharp
+using GitHub.Copilot;
+
+await using var client = new CopilotClient(new CopilotClientOptions
+{
+    ClientInfo = new CopilotClientInfo
+    {
+        ApplicationName = "vscode",
+        ApplicationVersion = "1.124.2",
+        IntegrationName = "copilot-chat",
+        IntegrationVersion = "0.54.0",
+    },
+});
+
+await client.StartAsync();
+```
+
+{% endcodetab %}
+{% codetab java %}
+
+```java
+var options = new CopilotClientOptions()
+    .setClientInfo(new ClientInfo()
+        .setApplicationName("vscode")
+        .setApplicationVersion("1.124.2")
+        .setIntegrationName("copilot-chat")
+        .setIntegrationVersion("0.54.0"));
+
+var client = new CopilotClient(options);
+client.start().get();
+```
+
+{% endcodetab %}
+{% codetab rust %}
+
+```rust
+use github_copilot_sdk::{Client, ClientInfo, ClientOptions};
+
+let client = Client::start(
+    ClientOptions::new().with_client_info(
+        ClientInfo::new()
+            .with_application_name("vscode")
+            .with_application_version("1.124.2")
+            .with_integration_name("copilot-chat")
+            .with_integration_version("0.54.0"),
+    ),
+)
+.await?;
+```
+
+{% endcodetab %}
+{% endcodetabs %}
+
+## Notes
+
+* Client info is advisory. The runtime can ignore values that do not match the expected format, such as an invalid version string.
+* Setting client info changes how the runtime attributes its telemetry. It does not change what the runtime records.
+* If every field is unset or empty, the SDK omits client info from the handshake and the runtime keeps its default attribution.

content/copilot/how-tos/copilot-sdk/auth/authenticate.md

@@ -26,13 +26,13 @@ A hook is a callback you register once when creating a session. The SDK invokes
 
 | Hook                                                                | When it fires                       | What you can do                            |
 | ------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------ |
-| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start)     | Session begins (new or resumed)     | Inject context, load preferences           |
+| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start-hook)     | Session begins (new or resumed)     | Inject context, load preferences           |
 | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)        | User sends a message                | Rewrite prompts, add context, filter input |
 | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed)    | Runtime builds the model prompt     | Inspect or replace model-facing content    |
 | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)                          | Before a tool executes              | Allow / deny / modify the call             |
 | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/post-tool-use)                        | After a tool returns (success only) | Transform results, redact secrets, audit   |
 | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/post-tool-use#failure-variant) | After a tool returns a failure      | Inject retry guidance, log failures        |
-| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end)         | Session ends                        | Clean up, record metrics                   |
+| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end-hook)         | Session ends                        | Clean up, record metrics                   |
 | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling)                     | An error is raised                  | Custom logging, retry logic, alerts        |
 
 All hooks are **optional**—register only the ones you need. Returning `null` (or the language equivalent) from any hook tells the SDK to continue with default behavior.

content/copilot/how-tos/copilot-sdk/auth/byok.md

@@ -13,6 +13,7 @@ contentType: how-tos
 children:
   - /agent-loop
   - /citations
+  - /client-info
   - /cloud-sessions
   - /context-management
   - /custom-agents

content/copilot/how-tos/copilot-sdk/features/client-info.md

@@ -160,6 +160,34 @@ let client = Client::start(
 
 > The example above uses an stdio runtime connection — the default when the SDK bundles the CLI. If you connect to an external runtime via a URL (`forUri` / `ForUri`), pass `--plugin-dir` to the long-running CLI server when you start it; the SDK does not forward `--plugin-dir` to runtimes it didn't spawn.
 
+## Per-session plugin directories
+
+`--plugin-dir` is a launch argument, so it fixes one plugin set for the CLI process and every session created against it. When sessions need different plugin sets, or when the SDK is connected to a runtime it did not spawn, pass the directories on the session config instead. They travel in the `session.create` and `session.resume` payloads over JSON-RPC rather than as process arguments, so they reach an external runtime the same way the startup option does.
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+  pluginDirectories: ["./plugins/code-reviewer"],
+});
+```
+
+Relative paths resolve against `workingDirectory`, or the runtime working directory when that is unset, so absolute paths are recommended. Entries that do not resolve are logged and skipped rather than failing session creation. The option is an explicit opt-in, which means plugin agents and rules load even when `enableConfigDiscovery` is false. Assets loaded this way sit between project sources and personal or home sources in the session-wide precedence order.
+
+The equivalent option in each SDK is:
+
+| SDK | Session option |
+|---|---|
+| Node.js / TypeScript | `pluginDirectories: string[]` |
+| Python | `plugin_directories=[...]` |
+| Go | `PluginDirectories: []string{...}` |
+| .NET | `PluginDirectories = [...]` |
+| Java | `.setPluginDirectories(List.of(...))` |
+| Rust | `.with_plugin_directories([...])` |
+
 ## Trusted host-bundled plugin directories
 
 Applications that ship their own trusted plugins can register them as a client startup option. The SDK sends the complete ordered set after connecting and verifying the protocol, before `start` returns or any session can be created. Paths must be absolute; leaving the option unset or empty makes no RPC call.