diff --git a/docs/auth/byok.md b/docs/auth/byok.md index d453b8113d..f80bc5d2ca 100644 --- a/docs/auth/byok.md +++ b/docs/auth/byok.md @@ -207,7 +207,7 @@ client.stop().get(); | `bearerToken` / `bearer_token` | string | Bearer token auth (takes precedence over apiKey) | | `bearerTokenProvider` / `bearer_token_provider` | callback | Returns a bearer token on demand (takes precedence over `apiKey` and `bearerToken`) | | `wireApi` / `wire_api` | `"completions"` \| `"responses"` | Select `"completions"` for broad model compatibility (the Chat Completions API); select `"responses"` for multi-turn state management, tool namespacing, and reasoning support (the Responses API). Anthropic models always use the Messages API regardless of this setting. | -| `azure.apiVersion` / `azure.api_version` | string | Azure API version (default: `"2024-10-21"`) | +| `azure.apiVersion` / `azure.api_version` | string | Azure API version. When set, the runtime uses the versioned deployment route; when omitted, it uses the GA versionless `v1` route. | ### Wire API format diff --git a/docs/features/custom-agents.md b/docs/features/custom-agents.md index 0cb68b9448..292f586dbb 100644 --- a/docs/features/custom-agents.md +++ b/docs/features/custom-agents.md @@ -254,12 +254,12 @@ try (var client = new CopilotClient()) { | `infer` | `boolean` | | Whether the runtime can auto-select this agent (default: `true`) | | `skills` | `string[]` | | Skill names to preload into the agent's context at startup | | `model` | `string` | | Model identifier to use while this agent runs | -| `reasoningEffort` | `string` | | Reasoning effort to use while this agent runs. When omitted, no override is sent and the backend chooses its default | +| `reasoningEffort` | `string` | | Reasoning effort to use while this agent runs. When omitted, the SDK sends no per-agent override and the runtime resolves the effort (see note below) | > [!TIP] > A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities. -Set `model` and `reasoningEffort` to override the parent session's model settings while a custom agent runs. When `reasoningEffort` is omitted, the SDK sends no per-agent override and the backend chooses its default. The parent session effort is not inherited, and the SDK does not add a per-agent default. Python uses `reasoning_effort`, .NET uses `ReasoningEffort`, Go uses `ReasoningEffort`, Java uses `setReasoningEffort`, and Rust uses `with_reasoning_effort`. +Set `model` and `reasoningEffort` to override the parent session's model settings while a custom agent runs. When `reasoningEffort` is omitted, the SDK sends no per-agent override and the runtime resolves the effort from its own precedence: a per-call client option, the resolved model's default, or the agent definition all take priority; otherwise the runtime inherits the parent session's effort only when the subagent runs the same model as the parent. When the subagent resolves to a different model, it falls back to that model's default instead of inheriting the parent's effort. Python uses `reasoning_effort`, .NET uses `ReasoningEffort`, Go uses `ReasoningEffort`, Java uses `setReasoningEffort`, and Rust uses `with_reasoning_effort`. In addition to per-agent configuration above, you can set `agent` on the **session config** itself to pre-select which custom agent is active when the session starts. See [Selecting an Agent at Session Creation](#selecting-an-agent-at-session-creation) below. diff --git a/docs/hooks/user-prompt-submitted.md b/docs/hooks/user-prompt-submitted.md index 49930ba4ac..230afca962 100644 --- a/docs/hooks/user-prompt-submitted.md +++ b/docs/hooks/user-prompt-submitted.md @@ -415,11 +415,11 @@ const session = await client.createSession({ }); ``` -### Rate limiting +### Usage threshold notices ```typescript const promptTimestamps: number[] = []; -const RATE_LIMIT = 10; // prompts +const NOTICE_THRESHOLD = 10; // prompts const RATE_WINDOW = 60000; // 1 minute const session = await client.createSession({ @@ -431,15 +431,16 @@ const session = await client.createSession({ while (promptTimestamps.length > 0 && promptTimestamps[0] < now - RATE_WINDOW) { promptTimestamps.shift(); } - - if (promptTimestamps.length >= RATE_LIMIT) { + + promptTimestamps.push(now); + if (promptTimestamps.length >= NOTICE_THRESHOLD) { + // This is advisory context for the model, not an enforced rate limit. + // Enforce hard limits before calling session.send(). return { - reject: true, - rejectReason: `Rate limit exceeded. Please wait before sending more prompts.`, + additionalContext: `The user has sent ${promptTimestamps.length} prompts in the last minute. Suggest waiting before sending more.`, }; } - - promptTimestamps.push(now); + return null; }, }, @@ -490,7 +491,7 @@ const session = await client.createSession({ 1. **Use `additionalContext` over `modifiedPrompt`** - Adding context is less intrusive than rewriting the prompt. -1. **Provide clear rejection reasons** - When rejecting prompts, explain why and how to fix it. +1. **Use `additionalContext` for advisory guidance**: This hook cannot reject a prompt or enforce policy. Enforce hard limits before calling `session.send()`. 1. **Keep processing fast** - This hook runs on every user message. Avoid slow operations. diff --git a/docs/setup/bundled-cli.md b/docs/setup/bundled-cli.md index 7c7d2fbbc4..f067de8fde 100644 --- a/docs/setup/bundled-cli.md +++ b/docs/setup/bundled-cli.md @@ -79,7 +79,7 @@ await client.stop() Go > [!NOTE] -> The Go SDK does not bundle the CLI. You must install the CLI separately or set `Connection` to point to an existing binary. See [Local CLI Setup](./local-cli.md) for details. +> Unlike Node.js, Python, and .NET, the Go SDK does not include a CLI as an automatic dependency. With no explicit path, `NewClient(nil)` uses an embedded CLI when available, then falls back to `copilot` on `PATH`. To embed a CLI, run the [bundler tool](../../go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli) at build time. You can also set `COPILOT_CLI_PATH` or point a `Connection` at an existing binary. See [Local CLI Setup](./local-cli.md) for details. ```go @@ -145,7 +145,7 @@ Console.WriteLine(response?.Data.Content); Java > [!NOTE] -> The Java SDK does not bundle or embed the Copilot CLI. You must install the CLI separately and configure its path via `Connection` or the `COPILOT_CLI_PATH` environment variable. +> The Java SDK does not bundle or embed the Copilot CLI. Install the CLI separately and either make `copilot` available on your `PATH` or set its location with `setCliPath(...)` (or connect to a running CLI server with `setCliUrl(...)`). ```java import com.github.copilot.CopilotClient; diff --git a/docs/setup/local-cli.md b/docs/setup/local-cli.md index 72394b3481..79a656396e 100644 --- a/docs/setup/local-cli.md +++ b/docs/setup/local-cli.md @@ -2,7 +2,7 @@ Use a specific CLI binary instead of the SDK's automatic CLI management. This is an advanced option—you supply the CLI path explicitly, and you are responsible for ensuring version compatibility with the SDK. -**Use when:** You need to pin a specific CLI version, or work with the Go SDK (which does not bundle a CLI). +**Use when:** You need to pin a specific CLI version, or work with the Go SDK (which does not include a CLI automatically). ## How it works @@ -78,7 +78,7 @@ await client.stop() Go > [!NOTE] -> The Go SDK does not bundle a CLI, so you must always provide `Connection`. +> The Go SDK does not ship a CLI automatically. Install `copilot` on `PATH`, set the `COPILOT_CLI_PATH` environment variable, embed a CLI with the [bundler tool](../../go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli), or point `StdioConnection.Path` at an installed binary. ```go diff --git a/dotnet/src/Types.cs b/dotnet/src/Types.cs index 127cf40305..81d891c784 100644 --- a/dotnet/src/Types.cs +++ b/dotnet/src/Types.cs @@ -2275,7 +2275,7 @@ public sealed class CapiSessionOptions public sealed class AzureOptions { /// - /// Azure OpenAI API version to use (e.g., "2024-02-01"). + /// Azure OpenAI API version. When omitted, the runtime uses the GA versionless v1 route. /// [JsonPropertyName("apiVersion")] public string? ApiVersion { get; set; } @@ -2660,8 +2660,8 @@ public sealed class CustomAgentConfig /// /// Reasoning effort level for this agent's model. - /// When omitted, no per-agent override is sent and the backend chooses its - /// default. The parent session effort is not inherited. + /// When omitted, the runtime resolves model configuration, then inherits + /// the parent effort only if this agent uses the same model. /// [JsonPropertyName("reasoningEffort")] public string? ReasoningEffort { get; set; } diff --git a/go/README.md b/go/README.md index 44ba01d66a..69c601ec17 100644 --- a/go/README.md +++ b/go/README.md @@ -591,7 +591,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K - `APIKey` (string): API key (optional for local providers like Ollama) - `BearerToken` (string): Bearer token for authentication (takes precedence over APIKey) - `WireAPI` (string): API format for OpenAI/Azure - "completions" or "responses" (default: "completions") -- `Azure.APIVersion` (string): Azure API version (default: "2024-10-21") +- `Azure.APIVersion` (string): Azure API version; when empty, the runtime uses the GA versionless `v1` route **Example with Ollama:** diff --git a/go/types.go b/go/types.go index d97fab9116..feec233c40 100644 --- a/go/types.go +++ b/go/types.go @@ -950,8 +950,8 @@ type CustomAgentConfig struct { // falling back to the parent session model if unavailable. Model string `json:"model,omitempty"` // ReasoningEffort is the reasoning effort level for this agent's model. - // When empty, no per-agent override is sent and the backend chooses its - // default. The parent session effort is not inherited. + // When empty, the runtime resolves model configuration, then inherits the + // parent effort only for the same model. ReasoningEffort string `json:"reasoningEffort,omitempty"` } @@ -1966,7 +1966,8 @@ type CapiSessionOptions struct { // AzureProviderOptions contains Azure-specific provider configuration type AzureProviderOptions struct { - // APIVersion is the Azure API version. Defaults to "2024-10-21". + // APIVersion is the Azure API version. When empty, the runtime uses the GA + // versionless v1 route. APIVersion string `json:"apiVersion,omitempty"` } diff --git a/java/src/main/java/com/github/copilot/rpc/AzureOptions.java b/java/src/main/java/com/github/copilot/rpc/AzureOptions.java index 7adbc5656b..cd25e845eb 100644 --- a/java/src/main/java/com/github/copilot/rpc/AzureOptions.java +++ b/java/src/main/java/com/github/copilot/rpc/AzureOptions.java @@ -12,6 +12,7 @@ *

* When using a BYOK (Bring Your Own Key) setup with Azure OpenAI, this class * allows you to specify Azure-specific settings such as the API version to use. + * When no API version is set, the runtime uses the GA versionless v1 route. * *

Example Usage

* @@ -32,7 +33,8 @@ public class AzureOptions { /** * Gets the Azure OpenAI API version. * - * @return the API version string + * @return the API version string, or {@code null} to use the GA versionless v1 + * route */ public String getApiVersion() { return apiVersion; @@ -41,7 +43,8 @@ public String getApiVersion() { /** * Sets the Azure OpenAI API version to use. *

- * Examples: {@code "2024-02-01"}, {@code "2023-12-01-preview"} + * Examples: {@code "2024-02-01"}, {@code "2023-12-01-preview"} When this option + * is not set, the runtime uses the GA versionless v1 route. * * @param apiVersion * the API version string diff --git a/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java b/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java index 3604a1ef5d..62de19b6a0 100644 --- a/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java +++ b/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java @@ -298,8 +298,8 @@ public String getReasoningEffort() { /** * Sets the reasoning effort level for this agent's model. *

- * When omitted, no per-agent override is sent and the backend chooses its - * default. The parent session effort is not inherited. + * When omitted, the runtime resolves model configuration, then inherits the + * parent effort only if this agent uses the same model. * * @param reasoningEffort * the reasoning effort level diff --git a/nodejs/README.md b/nodejs/README.md index 52b3d28053..df6414adaa 100644 --- a/nodejs/README.md +++ b/nodejs/README.md @@ -751,7 +751,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K - `apiKey?: string` - API key (optional for local providers like Ollama) - `bearerToken?: string` - Bearer token for authentication (takes precedence over apiKey) - `wireApi?: "completions" | "responses"` - API format for OpenAI/Azure (default: "completions") -- `azure?.apiVersion?: string` - Azure API version (default: "2024-10-21") +- `azure?.apiVersion?: string` - Azure API version; when omitted, the runtime uses the GA versionless `v1` route **Example with Ollama:** diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts index e48c9064c1..18443df599 100644 --- a/nodejs/src/types.ts +++ b/nodejs/src/types.ts @@ -1643,8 +1643,8 @@ export interface CustomAgentConfig { model?: string; /** * Reasoning effort level for this agent's model. - * When omitted, no per-agent override is sent and the backend chooses its - * default. The parent session effort is not inherited. + * When omitted, the runtime resolves the effort from model configuration, + * then inherits the parent effort only if this agent uses the same model. */ reasoningEffort?: ReasoningEffort; } @@ -2619,7 +2619,7 @@ export interface ProviderConfig { */ azure?: { /** - * API version. Defaults to "2024-10-21". + * API version. When omitted, the runtime uses the GA versionless v1 route. */ apiVersion?: string; }; diff --git a/python/README.md b/python/README.md index 3089c36699..def8bd31fb 100644 --- a/python/README.md +++ b/python/README.md @@ -586,7 +586,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K - `api_key` (str): API key (optional for local providers like Ollama) - `bearer_token` (str): Bearer token for authentication (takes precedence over `api_key`) - `wire_api` (str): API format for OpenAI/Azure - `"completions"` or `"responses"` (default: `"completions"`) -- `azure` (dict): Azure-specific options with `api_version` (default: `"2024-10-21"`) +- `azure` (dict): Azure-specific options with `api_version`; when omitted, the runtime uses the GA versionless `v1` route **Example with Ollama:** diff --git a/python/copilot/session.py b/python/copilot/session.py index b6736939ac..f732481163 100644 --- a/python/copilot/session.py +++ b/python/copilot/session.py @@ -1080,8 +1080,8 @@ class CustomAgentConfig(TypedDict, total=False): skills: NotRequired[list[str]] # Model identifier (e.g. "claude-haiku-4.5"); runtime falls back to parent model if unavailable model: NotRequired[str] - # Reasoning effort for this agent's model. When omitted, no per-agent override - # is sent and the backend chooses its default; the parent effort is not inherited. + # Reasoning effort for this agent's model. When omitted, the runtime resolves + # model configuration, then inherits the parent effort only for the same model. reasoning_effort: NotRequired[ReasoningEffort] @@ -1183,7 +1183,8 @@ class MemoryConfiguration(TypedDict): class AzureProviderOptions(TypedDict, total=False): """Azure-specific provider configuration""" - api_version: str # Azure API version. Defaults to "2024-10-21". + # Azure API version. When omitted, the runtime uses the GA versionless v1 route. + api_version: str class ProviderTokenArgs(TypedDict): diff --git a/rust/src/types.rs b/rust/src/types.rs index dcbb51e488..163e1d29c0 100644 --- a/rust/src/types.rs +++ b/rust/src/types.rs @@ -644,8 +644,8 @@ pub struct CustomAgentConfig { pub model: Option, /// Reasoning effort level for this agent's model. /// - /// When unset, no per-agent override is sent and the backend chooses its - /// default. The parent session effort is not inherited. + /// When unset, the runtime resolves model configuration, then inherits the + /// parent effort only for the same model. #[serde(default, skip_serializing_if = "Option::is_none")] pub reasoning_effort: Option, } @@ -1351,7 +1351,7 @@ impl CapiSessionOptions { #[derive(Debug, Clone, Default, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct AzureProviderOptions { - /// Azure API version. Defaults to `"2024-10-21"`. + /// Azure API version. When omitted, the runtime uses the GA versionless v1 route. #[serde(default, skip_serializing_if = "Option::is_none")] pub api_version: Option, }