@alvin0/ai-agent-sdk-provider-copilot 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1297 @@
+import { AgentSdkError, ModelInvocationContext, RetryPolicyConfig, SafeErrorRecord } from "@alvin0/ai-agent-sdk-core";
+import { ComposableModelProviderPlugin, CredentialOperationOptions, CredentialStore, ModelTarget } from "@alvin0/ai-agent-sdk-core/provider";
+import { HttpModelAdapter, ProtocolRequest, ProtocolSseEvent, ProtocolStreamChunk, ProviderCatalogModel, ProviderRequestLogger, RuntimeModelDiscoveryContext, RuntimeWireProtocol } from "@alvin0/ai-agent-sdk-provider-http";
+import { ChatCompletionsDialect } from "@alvin0/ai-agent-sdk-protocol-openai-chat-completions";
+import { ResponsesDialect } from "@alvin0/ai-agent-sdk-protocol-responses";
+//#region src/catalog.d.ts
+/** Path of the catalog surface, relative to the pinned Copilot base URL. */
+declare const COPILOT_CATALOG_PATH = "/models";
+/** Maximum raw catalog bytes when the caller configures none. */
+declare const COPILOT_DEFAULT_MAX_CATALOG_BYTES: number;
+/** Maximum catalog entries accepted when the caller configures none. */
+declare const COPILOT_DEFAULT_MAX_CATALOG_MODELS = 2048;
+/** Maximum catalog response chunks accepted when the caller configures none. */
+declare const COPILOT_DEFAULT_MAX_CATALOG_CHUNKS = 10000;
+/** Catalog request deadline when the caller configures none. */
+declare const COPILOT_DEFAULT_CATALOG_TIMEOUT_MS = 30000;
+/**
+ * Which endpoint a generation model is dispatched to.
+ *
+ * Declared HERE rather than in `./router.ts`, where the router's own types live,
+ * for one structural reason: `./router.ts` imports {@link CopilotGenerationModel}
+ * from this module, so the dependency edge already runs router → catalog. Putting
+ * the endpoint union in the router would make it run both ways, which the repo's
+ * source-ownership check forbids and which nothing here needs. `./router.ts`
+ * re-exports this type, so the router remains the module a reader goes to for
+ * endpoint selection.
+ */
+type CopilotEndpoint = 'responses' | 'chat-completions';
+/** Why an entry was left out of both catalogs. */
+type CopilotOmitReason =
+/** capabilities.type is not one of the recognized values. */
+'capability-type-unrecognized' |
+/** No usable id. */
+'model-id-missing';
+/** One entry that was dropped, with the reason an operator needs to see it. */
+interface CopilotOmittedModel {
+  /** The entry's id, or `''` when it had none — the reason says which. */
+  readonly id: string;
+  /** Why it was dropped. */
+  readonly reason: CopilotOmitReason;
+}
+/** A generation model, plus whatever the catalog disclosed about its endpoint. */
+interface CopilotGenerationModel {
+  /** The SDK catalog model, handed to `provider-http` unchanged. */
+  readonly model: ProviderCatalogModel;
+  /**
+   * The endpoint the catalog disclosed, when it disclosed one.
+   *
+   * `undefined` means UNKNOWN, not "not supported". The router handles those two
+   * states differently (Requirement 8.6).
+   */
+  readonly declaredEndpoint: CopilotEndpoint | undefined;
+}
+/**
+ * An embedding model, carrying only the facts the catalog stated.
+ *
+ * Deliberately NOT a {@link ProviderCatalogModel}: an embedding model has no
+ * context window or output cap to report, and `Copilot_Embedding_Adapter` needs
+ * different facts (batch ceiling, whether a requested dimension count is
+ * honoured). Every field but `id` is optional because every one of them is absent
+ * from some real entry.
+ */
+interface CopilotEmbeddingModel {
+  /** Wire model id, passed to the endpoint verbatim. */
+  readonly id: string;
+  /** Display label, when the catalog supplied one. */
+  readonly name?: string;
+  /** Model family, when disclosed; embedding compatibility identity is derived from it. */
+  readonly family?: string;
+  /** Token ceiling for one input, from `limits.max_context_window_tokens`. */
+  readonly maxInputTokens?: number;
+  /** Ceiling on inputs per request, from `limits.max_inputs`. */
+  readonly maxInputs?: number;
+  /** Whether `supports.dimensions` was stated, and what it said. */
+  readonly supportsDimensions?: boolean;
+}
+/** The result of one discovery, partitioned. */
+interface CopilotCatalogSnapshot {
+  /** Models usable for generation, each with its preliminary endpoint disclosure. */
+  readonly generation: readonly CopilotGenerationModel[];
+  /** Models usable for embedding. */
+  readonly embedding: readonly CopilotEmbeddingModel[];
+  /** Dropped entries with their reasons — these go to observation, not to a catalog. */
+  readonly omitted: readonly CopilotOmittedModel[];
+}
+/** Resolved bounds for one catalog read. Every field is a bound, never "unlimited". */
+interface CopilotCatalogLimits {
+  /** Maximum raw response bytes. */
+  readonly maxBytes: number;
+  /** Maximum entries accepted before the response is called malformed. */
+  readonly maxModels: number;
+  /** Maximum response chunks. */
+  readonly maxChunks: number;
+  /** Deadline for the catalog request AND its body read. */
+  readonly timeoutMs: number;
+  /** Permit an `http:` base URL for a trusted local test endpoint. */
+  readonly allowInsecureHttp?: boolean;
+}
+/**
+ * The caller-facing catalog options, in the spelling `CopilotProviderOptions` uses.
+ *
+ * Split into two groups on purpose. The four `max*`/`timeout` values bound ONE
+ * read and are resolved here by {@link resolveCopilotCatalogLimits}. The three
+ * cache values (TTL, stale TTL, failure backoff) bound how often reads happen at
+ * all, and `provider-http` already owns that policy — {@link
+ * copilotCatalogCacheOptions} forwards them without a default, so an unset option
+ * keeps the runtime's own default instead of this package pinning a second one
+ * (Requirement 8.7).
+ */
+interface CopilotCatalogOptions {
+  /** Maximum raw catalog bytes. Defaults to {@link COPILOT_DEFAULT_MAX_CATALOG_BYTES}. */
+  readonly maxCatalogBytes?: number;
+  /** Maximum catalog entries. Defaults to {@link COPILOT_DEFAULT_MAX_CATALOG_MODELS}. */
+  readonly maxCatalogModels?: number;
+  /** Maximum catalog response chunks. Defaults to {@link COPILOT_DEFAULT_MAX_CATALOG_CHUNKS}. */
+  readonly maxCatalogChunks?: number;
+  /** Catalog request deadline. Defaults to {@link COPILOT_DEFAULT_CATALOG_TIMEOUT_MS}. */
+  readonly catalogTimeoutMs?: number;
+  /** How long a discovered catalog stays fresh. */
+  readonly catalogTtlMs?: number;
+  /** How long a stale catalog may still be served while a refresh is attempted. */
+  readonly catalogStaleTtlMs?: number;
+  /** How long to wait before retrying discovery after it failed. */
+  readonly catalogFailureBackoffMs?: number;
+  /** Permit an `http:` base URL for a trusted local test endpoint. */
+  readonly allowInsecureHttp?: boolean;
+}
+/**
+ * Resolve the per-read bounds, rejecting a value that cannot bound anything.
+ *
+ * Validation happens here rather than at the read, so a `0` or a `NaN` in the
+ * configuration is a construction-time error instead of a silently disabled limit
+ * discovered under load (Requirement 8.2).
+ * @param options - the caller's catalog options.
+ * @returns the four resolved bounds plus the insecure-HTTP opt-in.
+ * @throws RangeError when a configured bound is not a positive safe integer.
+ */
+declare function resolveCopilotCatalogLimits(options?: CopilotCatalogOptions): CopilotCatalogLimits;
+/**
+ * Forward the three cache-policy options, and only the ones that were set.
+ *
+ * A conditional spread rather than defaults: `provider-http` owns catalog caching,
+ * and a default written here would override the runtime's own without anyone
+ * asking for it (Requirement 8.7).
+ * @param options - the caller's catalog options.
+ * @returns an object carrying only the cache options the caller supplied.
+ */
+declare function copilotCatalogCacheOptions(options?: CopilotCatalogOptions): {
+  readonly catalogTtlMs?: number;
+  readonly catalogStaleTtlMs?: number;
+  readonly catalogFailureBackoffMs?: number;
+};
+/**
+ * Read `GET {baseUrl}/models` and partition it.
+ *
+ * The base URL is re-pinned here from `context.baseUrl` rather than trusted as a
+ * string: the catalog is the first Copilot call an adapter makes, and a pin
+ * compared before dispatch is the only check that runs before the resolved
+ * `Authorization` header leaves the process.
+ * @param context - the discovery context `provider-http` supplies: base URL,
+ *   already-resolved headers, and the operation's signal.
+ * @param limits - bounds from {@link resolveCopilotCatalogLimits}.
+ * @param fetchImpl - HTTP implementation, injected for tests and non-browser runtimes.
+ * @returns the partitioned snapshot; an empty one when the endpoint answered a
+ *   non-2xx status, because a catalog that could not be fetched is advisory too.
+ * @throws AgentSdkError with `COPILOT_REDIRECT_REJECTED` on any redirect shape, or
+ *   `COPILOT_CATALOG_MALFORMED` when the response is the wrong shape structurally.
+ * @throws RangeError when the response exceeds a configured bound.
+ */
+declare function discoverCopilotModels(context: RuntimeModelDiscoveryContext, limits: CopilotCatalogLimits, fetchImpl: typeof globalThis.fetch): Promise<CopilotCatalogSnapshot>;
+/**
+ * Partition an already-read catalog body.
+ *
+ * Exported separately from the fetch so the partition is testable — and readable —
+ * as what it is: a pure function from a parsed body to three lists.
+ * @param body - the parsed root object of the catalog response.
+ * @param maxModels - entry-count ceiling; exceeding it is structural, not per-entry.
+ * @returns the partitioned snapshot.
+ * @throws AgentSdkError with `COPILOT_CATALOG_MALFORMED` when `data` is not an
+ *   array or holds more than `maxModels` entries.
+ */
+declare function partitionCopilotCatalog(body: Record<string, unknown>, maxModels: number): CopilotCatalogSnapshot;
+//#endregion
+//#region src/common/identity.d.ts
+/**
+ * The two Copilot endpoint constants and the editor-header override type, in the
+ * leaf layer so every module that has to speak to the Copilot surface can reach
+ * them.
+ *
+ * They BELONG to `../adapter.ts` — that module is the public door, documents the
+ * client-identity tradeoff, and re-exports everything here. The values live one
+ * layer down for the same structural reason `COPILOT_ERROR_CODES` does:
+ * `../catalog.ts` needs {@link COPILOT_BASE_URL} and `../exchange.ts` needs the
+ * two editor headers, while `../adapter.ts` builds the catalog reader and the
+ * token cache. Declaring the constants in `../adapter.ts` would make that edge
+ * run both ways, which the repo's circular-dependency check forbids. Copying the
+ * strings instead would be worse: a client identity that exists in two places is
+ * a client identity that can disagree with itself.
+ *
+ * Read `../adapter.ts` for what these values mean, why they are overridable
+ * options rather than hidden constants, and what is still outstanding on each.
+ *
+ * @module ai-agent-sdk/providers/copilot/identity
+ */
+/** The Copilot API base. Documented on the re-export in `../adapter.ts`. */
+declare const COPILOT_BASE_URL = "https://api.githubcopilot.com";
+/** Default `Editor-Version`. Documented on the re-export in `../adapter.ts`. */
+declare const COPILOT_EDITOR_VERSION = "vscode/1.99.0";
+/** Default `Editor-Plugin-Version`. Documented on the re-export in `../adapter.ts`. */
+declare const COPILOT_EDITOR_PLUGIN_VERSION = "copilot-chat/0.26.0";
+/**
+ * Overrides for the two editor headers.
+ *
+ * Each field is independent: leaving one undefined keeps that header's exported
+ * default rather than dropping the header, because a dropped header is an HTTP
+ * 400 rather than a lenient request.
+ */
+interface CopilotEditorHeaders {
+  /** Overrides {@link COPILOT_EDITOR_VERSION}. */
+  readonly editorVersion?: string;
+  /** Overrides {@link COPILOT_EDITOR_PLUGIN_VERSION}. */
+  readonly editorPluginVersion?: string;
+}
+//#endregion
+//#region src/common/store-types.d.ts
+/**
+ * The long-lived GitHub user token, prefixed `ghu_`.
+ *
+ * It DOES NOT rotate when it is exchanged for a `Copilot_Api_Token`. That is the
+ * structural difference from Codex's single-use refresh token, and it is why the
+ * credential file is written exactly once at login and only read from then on.
+ */
+interface CopilotGitHubToken {
+  /** The token value. Never put this in an error message or a trace. */
+  readonly token: string;
+  /** Token type as declared by the endpoint, when present. Diagnostics only. */
+  readonly tokenType?: string;
+  /** Granted scope, when the endpoint discloses it. Diagnostics only. */
+  readonly scope?: string;
+}
+/** Session identity, limited to what the endpoint actually discloses. */
+interface CopilotAccountIdentity {
+  readonly login?: string;
+  readonly id?: number;
+  readonly name?: string;
+}
+/**
+ * The persisted credential document.
+ *
+ * Four things are deliberately absent, each one a decision:
+ *
+ * - **No `Copilot_Api_Token`.** The short-lived token lives ~25 minutes;
+ *   persisting it adds a write path and a second secret on disk while saving
+ *   nothing, because the next process run almost always has to exchange again.
+ * - **No refresh-token field.** There is no refresh token in this model.
+ *   `Copilot_Token_Exchange` does not consume the credential, so there is
+ *   nothing to rotate.
+ * - **No `last_refresh`.** Codex needs it as a fallback when `exp` is
+ *   unreadable. Copilot reads `expires_at` straight from the exchange response,
+ *   and that response lives in memory rather than in this file, so a
+ *   file-age fallback would have nothing to say.
+ * - **No API-key-equivalent config.** This surface rejects personal access
+ *   tokens, so a "use an API key instead of OAuth" configuration has no
+ *   situation to represent.
+ */
+interface CopilotAuthFile {
+  /**
+   * Structure version. Reading a file with an unknown version is an error, not
+   * an implicit migration.
+   */
+  readonly version: 1;
+  readonly github: CopilotGitHubToken;
+  readonly account?: CopilotAccountIdentity;
+  /** The OAuth client id that minted this token; used to diagnose a 403. */
+  readonly clientId?: string;
+  /** Login time, ISO-8601. */
+  readonly obtainedAt?: string;
+}
+/**
+ * @deprecated Read/write variant, kept only for symmetry with Codex. Normal
+ * runtime composition uses {@link CopilotCredentialStore}.
+ */
+interface CopilotAuthStore {
+  readonly location: string;
+  read(): Promise<CopilotAuthFile | undefined>;
+  write(file: CopilotAuthFile): Promise<void>;
+}
+/** Compare-and-swap variant used by normal runtime composition. */
+type CopilotCredentialStore = CredentialStore<CopilotAuthFile>;
+//#endregion
+//#region src/router.d.ts
+/**
+ * Model id prefixes dispatched to `/responses` when the catalog says nothing.
+ *
+ * Exported and overridable for the same reason `COPILOT_EDITOR_VERSION` is: this
+ * is a fact about a remote endpoint that WILL go stale, and a user has to be able
+ * to correct it without waiting for a release.
+ * `CopilotProviderOptions.responsesModelPrefixes` ADDS to this list rather than
+ * replacing it, so an override cannot silently drop the prefixes shipped here.
+ *
+ * Kept deliberately short. A prefix that matches too much pushes models toward
+ * the endpoint where guessing wrong costs the request (see the module note), so
+ * an absent prefix is the cheaper error.
+ */
+declare const COPILOT_RESPONSES_MODEL_PREFIXES: readonly string[];
+/** The endpoint chosen for one model id, and who chose it. */
+interface CopilotEndpointDecision {
+  /** The model id the decision is keyed by, verbatim as the caller spelled it. */
+  readonly model: string;
+  /** The endpoint the request goes to. */
+  readonly endpoint: CopilotEndpoint;
+  /** Wire protocol id of the sub-protocol that serves {@link endpoint}. */
+  readonly protocolId: string;
+  /**
+   * Which step of the decision order produced this.
+   *
+   * Reported to observation (Requirement 9.8) so that when a model runs against
+   * the wrong endpoint, the log says who decided rather than leaving an operator
+   * to reconstruct it.
+   */
+  readonly source: 'override' | 'catalog' | 'allowlist' | 'default';
+}
+/** Memoized, append-only endpoint selection for one adapter instance. */
+interface CopilotEndpointRouter {
+  /**
+   * Decide the endpoint for a model id.
+   *
+   * MEMOIZED AND APPEND-ONLY: a key that already has a decision is returned
+   * unchanged and never recomputed. This is the mechanism that makes
+   * Requirement 9.7 hold — no code path can change its mind between two retries.
+   * @param modelId - the wire model id of the request being dispatched.
+   * @returns the decision for that model, recording it on first sight.
+   */
+  decide(modelId: string): CopilotEndpointDecision;
+  /**
+   * Feed in discovered catalog metadata.
+   *
+   * Adds ONLY keys that have no decision yet; an id already decided is skipped
+   * even when the metadata now disagrees with the recorded decision.
+   * @param models - the generation half of a {@link CopilotGenerationModel} list.
+   */
+  learn(models: readonly CopilotGenerationModel[]): void;
+  /**
+   * Every decision recorded so far, in the order it was recorded.
+   * @returns a frozen snapshot, for `--models` and for the conformance harness.
+   */
+  snapshot(): readonly CopilotEndpointDecision[];
+}
+/** Construction options for {@link createCopilotEndpointRouter}. */
+interface CopilotEndpointRouterOptions {
+  /**
+   * Endpoints pinned by the application, keyed by model id. Wins over every
+   * other source, including a catalog disclosure that contradicts it.
+   */
+  readonly overrides?: Readonly<Record<string, CopilotEndpoint>>;
+  /**
+   * The full responses-prefix allowlist to use.
+   *
+   * The caller passes the already-merged list — `copilotAdapter` spreads
+   * {@link COPILOT_RESPONSES_MODEL_PREFIXES} first and the user's additions
+   * after — so the "adds, never replaces" rule is visible at the call site
+   * instead of hidden in here. Defaults to the shipped list when omitted.
+   */
+  readonly prefixes?: readonly string[];
+}
+/**
+ * Build a router for one adapter instance.
+ *
+ * Overrides are validated HERE, not at dispatch: a typo in
+ * `endpointOverrides` is a configuration mistake, and a configuration mistake
+ * that surfaces while building the provider is cheaper than one that surfaces on
+ * the first request to one particular model.
+ * @param options - overrides and the merged prefix allowlist.
+ * @returns a router whose `decisions` map only ever grows.
+ * @throws AgentSdkError with `COPILOT_ENDPOINT_OVERRIDE_INVALID` when an
+ *   override pins an endpoint that does not exist.
+ */
+declare function createCopilotEndpointRouter(options?: CopilotEndpointRouterOptions): CopilotEndpointRouter;
+//#endregion
+//#region src/dual-protocol.d.ts
+/** Protocol id the HTTP layer reports for every Copilot request. */
+declare const COPILOT_DUAL_PROTOCOL_ID = "copilot-dual";
+/**
+ * The Copilot dialect, FLAT on purpose.
+ *
+ * Declared in this module rather than in `./adapter.ts` — where the design's file
+ * map lists it — for one structural reason: `copilotAdapter` builds the composite,
+ * so the source edge already runs adapter → dual-protocol, and the two projection
+ * functions are runtime values. Declaring them in `./adapter.ts` would make that
+ * edge bidirectional, which the repo's circular-dependency check forbids. The
+ * public placement is preserved by re-export: `./adapter.ts` re-exports this type
+ * and both projections, the same way `./router.ts` re-exports `CopilotEndpoint`
+ * from `./catalog.ts`. DD-2 also puts ownership here —
+ * "the composite owns the two pure projection functions".
+ *
+ * Every field is a primitive or a string array. See rule 2 in the module note for
+ * why nesting the two sub-dialects instead would be a silent-data-loss bug.
+ */
+interface CopilotDialect {
+  /** Send temperature/top_p. Both endpoints accept them; some models refuse. */
+  readonly sampling: boolean;
+  /** Send the output-token limit. */
+  readonly maxOutputTokens: boolean;
+  /** Send JSON-schema structured output. */
+  readonly structuredOutputs: boolean;
+  /** Declare tools in the request. */
+  readonly tools: boolean;
+  /** Responses only: `store`. */
+  readonly store: boolean;
+  /** Responses only: `include`. */
+  readonly include: readonly string[];
+  /** Responses only: `reasoning.summary`. `'none'` asks for no summary at all. */
+  readonly reasoningSummary: 'auto' | 'concise' | 'detailed' | 'none';
+  /** Chat Completions only: `stream_options.include_usage`. */
+  readonly streamUsage: boolean;
+  /** Chat Completions only: the role the system prompt travels under. */
+  readonly systemRole: 'system' | 'developer';
+  /** Chat Completions only: `parallel_tool_calls`. */
+  readonly parallelToolCalls: boolean;
+  /** Prompt/session cache key, used by BOTH branches. */
+  readonly promptCacheKey?: string;
+}
+/**
+ * Conservative defaults, matching each sub-protocol's own defaults where the two
+ * agree.
+ *
+ * `store: false` because retaining prompts on someone else's server is an explicit
+ * decision, `include` carries `reasoning.encrypted_content` because without it a
+ * reasoning model loses its chain of thought across a tool call, and
+ * `parallelToolCalls: false` because older gateways reject the field outright.
+ */
+declare const COPILOT_DEFAULT_DIALECT: CopilotDialect;
+/**
+ * Project the Copilot dialect onto the Responses dialect.
+ *
+ * PURE and TOTAL: every {@link CopilotDialect} flag has exactly one destination
+ * here or none at all. `tools`, `streamUsage`, `systemRole` and
+ * `parallelToolCalls` have no Responses destination and are DROPPED rather than
+ * bent into a nearby flag — Responses declares tools from the request itself and
+ * has no `reasoning_effort`-style neighbour worth guessing at.
+ *
+ * `reasoningSummary: 'none'` is expressed by ABSENCE, because that is how the
+ * Responses serializer spells "ask for no summary" (`summary` is only sent when
+ * the knob is defined). {@link resolvedResponsesDialect} therefore drops the
+ * sub-protocol's own `reasoningSummary` default before merging, so this branch of
+ * the projection is not overwritten by it.
+ * @param dialect - the resolved Copilot dialect for this request.
+ * @returns the Responses knobs this dialect determines, and only those.
+ */
+declare function toResponsesDialect(dialect: CopilotDialect): Partial<ResponsesDialect>;
+/**
+ * Project the Copilot dialect onto the Chat Completions dialect.
+ *
+ * PURE and TOTAL, same rule as {@link toResponsesDialect}: `store`, `include` and
+ * `reasoningSummary` have no Chat Completions destination and are dropped —
+ * `reasoningEffort` is a different knob (how hard to think, not whether to report
+ * a summary), so mapping onto it would be a guess dressed as a translation.
+ *
+ * Two flags change type on the way across, and each mapping is total:
+ *
+ * | Copilot | Chat Completions |
+ * | --- | --- |
+ * | `maxOutputTokens: true` | `maxTokensField: 'max_tokens'` |
+ * | `maxOutputTokens: false` | `maxTokensField: false` |
+ * | `structuredOutputs: true` | `structuredOutputs: 'json-schema'` |
+ * | `structuredOutputs: false` | `structuredOutputs: false` |
+ *
+ * The accepted cost of the first row: a caller cannot reach
+ * `'max_completion_tokens'` through {@link CopilotDialect}. Copilot's
+ * `/chat/completions` takes `max_tokens`, and the models that demand the newer
+ * spelling are the ones the router sends to `/responses` anyway, so the boolean
+ * buys a flag a caller can reason about and costs a spelling no Copilot model has
+ * been observed to need.
+ * @param dialect - the resolved Copilot dialect for this request.
+ * @returns the Chat Completions knobs this dialect determines, and only those.
+ */
+declare function toChatCompletionsDialect(dialect: CopilotDialect): Partial<ChatCompletionsDialect>;
+/**
+ * The parts of a sub-protocol the composite uses.
+ *
+ * Structural rather than an import of either package's own definition type, so
+ * that a test can hand in a stub and so that neither sub-protocol's marker fields
+ * become part of this contract.
+ */
+interface CopilotSubProtocol<Dialect extends object> {
+  /** Reported on the decision as `protocolId`. */
+  readonly id: string;
+  /** Merged UNDER the projection by the composite; never read by the runtime. */
+  readonly defaultDialect: Dialect;
+  readonly endpointPath: (request: ProtocolRequest, dialect: Dialect) => string;
+  readonly protocolHeaders?: (dialect: Dialect) => Readonly<Record<string, string>>;
+  readonly serialize: (request: ProtocolRequest, dialect: Dialect) => Readonly<Record<string, unknown>>;
+  readonly translate: (events: AsyncIterable<ProtocolSseEvent>, request: ProtocolRequest, displayName: string) => AsyncGenerator<ProtocolStreamChunk>;
+}
+/** The `/responses` half. `openAiResponsesProtocol` satisfies this. */
+type ResponsesProtocolLike = CopilotSubProtocol<ResponsesDialect>;
+/** The `/chat/completions` half. `openAiChatCompletionsProtocol` satisfies this. */
+type ChatCompletionsProtocolLike = CopilotSubProtocol<ChatCompletionsDialect>;
+/** Construction options for {@link copilotDualProtocol}. */
+interface CopilotDualProtocolOptions {
+  /** Decides, once per model id, which branch a request takes. */
+  readonly router: CopilotEndpointRouter;
+  /** The protocol serving `/responses`. */
+  readonly responses: ResponsesProtocolLike;
+  /** The protocol serving `/chat/completions`. */
+  readonly chat: ChatCompletionsProtocolLike;
+  /**
+   * Synchronous, best-effort observer of every endpoint decision (Requirement
+   * 9.8).
+   *
+   * Carries `{ model, endpoint, protocolId, source }` — no prompt and no
+   * credential, because an observer is a diagnostic channel and neither of those
+   * is diagnostic. Throwing in here does NOT affect the request: the error is
+   * trapped, since a broken log sink must not decide whether a generation runs.
+   */
+  readonly onDecision?: (decision: CopilotEndpointDecision) => void;
+}
+/**
+ * Build the composite protocol.
+ *
+ * @param options - the router, the two sub-protocols, and the optional observer.
+ * @returns a `RuntimeWireProtocol<CopilotDialect>` with id `'copilot-dual'`.
+ */
+declare function copilotDualProtocol(options: CopilotDualProtocolOptions): RuntimeWireProtocol<CopilotDialect>;
+//#endregion
+//#region src/auth.d.ts
+/**
+ * The command that produces a credential, named in every message that tells a
+ * caller how to fix a credential problem.
+ *
+ * Exported so the token-exchange path names the SAME command: a 401 and a 403
+ * there both end in "sign in again", and two copies of that string are two
+ * strings that can drift apart.
+ */
+declare const COPILOT_LOGIN_COMMAND = "npm run provider:copilot:login-device";
+/**
+ * An in-memory {@link CopilotAuthStore} — the read/write variant (Requirement 6.4).
+ *
+ * The read/write variant exists for symmetry with Codex; normal runtime
+ * composition uses {@link memoryCopilotCredentialStore}, the compare-and-swap
+ * variant.
+ * @param initial - the file the store starts with, or nothing for an empty store.
+ * @returns a store backed by a single mutable slot.
+ */
+declare function memoryCopilotAuthStore(initial?: CopilotAuthFile): CopilotAuthStore;
+/**
+ * An in-memory compare-and-swap store, for deterministic runtime and tests
+ * (Requirements 6.2, 6.4).
+ *
+ * Values are `structuredClone`d in BOTH directions, which is the point of this
+ * double: a caller that mutates the object it wrote, or the object it read, must
+ * not be able to change what the store holds. Without the clone a test could pass
+ * for the wrong reason — the store and the caller sharing one object rather than
+ * the store having committed anything.
+ *
+ * A commit whose `expectedRevision` disagrees with the current revision raises
+ * {@link COPILOT_ERROR_CODES.CREDENTIAL_REVISION_CONFLICT} (Requirement 6.3), the
+ * Copilot-owned code, so exactly one of two concurrent commits wins and the loser
+ * can tell why it lost.
+ * @param initial - the file the store starts with, or nothing for an empty store.
+ * @returns a compare-and-swap store over a single mutable slot.
+ */
+declare function memoryCopilotCredentialStore(initial?: CopilotAuthFile): CopilotCredentialStore;
+/**
+ * One read of the credential store, carried through a single operation.
+ *
+ * `revision` travels with `file` rather than being re-read later, because the
+ * token cache keys on the pair: a file that changed under us has a different
+ * revision even when the token value happens to be identical.
+ */
+interface CopilotCredentialSnapshot {
+  readonly file: CopilotAuthFile;
+  /** The revision at read time, or `null` for a store with no revisions. */
+  readonly revision: string | null;
+  /** The store's human-readable location, named in diagnostics. */
+  readonly label: string;
+}
+/**
+ * Require a usable `GitHub_User_Token`, with a message that says how to get one.
+ *
+ * Three shapes of "there is no credential" — an empty store, a file with no
+ * `github` field, and a `github.token` that is the empty string — collapse into
+ * the SAME code, because to the person reading the error they are one problem
+ * with one fix. That code is the SDK's own {@link MISSING_CREDENTIAL_CODE} rather
+ * than a Copilot-specific one, so a consumer does not have to write a second
+ * branch for a situation it already handles, and the message carries the command
+ * to run `Copilot_Login_Cli` (Requirement 13.4).
+ *
+ * The token value is never interpolated into the message; only the store's label
+ * is (Requirement 13.7).
+ * @param file - the credential file, or `undefined` when the store was empty.
+ * @param label - the store location named in the diagnostic.
+ * @returns the long-lived GitHub token.
+ */
+declare function requireGitHubToken(file: CopilotAuthFile | undefined, label: string): CopilotGitHubToken;
+/** Exchange this long before the `Copilot_Api_Token` actually expires. */
+declare const COPILOT_TOKEN_EXCHANGE_MARGIN_MS: number;
+/**
+ * The part of a `Copilot_Api_Token` that {@link shouldExchange} reads.
+ *
+ * Declared here rather than imported so this module owns no dependency on the
+ * exchange module: expiry arithmetic is the whole of what the decision needs, and
+ * `CopilotApiToken` — which carries the token value and the declared endpoint
+ * besides — satisfies this shape structurally, so `shouldExchange` accepts one
+ * with no conversion and there is only ever one declaration of the full type.
+ */
+interface CopilotTokenExpiry {
+  /** Expiry instant in epoch MILLISECONDS, derived from the endpoint's `expires_at`. */
+  readonly expiresAtMs: number;
+  /** The endpoint's `refresh_in` hint, in seconds, when it sent one. Advisory. */
+  readonly refreshInSeconds?: number;
+}
+/**
+ * Whether a token exchange has to happen before the next request.
+ *
+ * A pure function of three values that reads no global clock, so a property test
+ * can place `now` at every boundary without a fake timer (Requirements 5.2, 5.3).
+ * `undefined` — no token yet — is always `true`.
+ *
+ * `expires_at` is the authority and `refresh_in` is advisory: the hint may only
+ * SHORTEN the refresh moment, never lengthen it. The endpoint is allowed to ask
+ * for an earlier exchange; it is not allowed to ask this SDK to hold a token past
+ * the expiry it announced itself.
+ *
+ * There is deliberately no fallback branch. `shouldRefresh` in
+ * `provider-codex/src/auth.ts` decodes a JWT for `exp` and falls back to a
+ * `last_refresh` age when it cannot; a `Copilot_Api_Token` is not a JWT this SDK
+ * has any business reading, and the expiry is stated outright in the exchange
+ * response body. With no second source, a fallback would have to invent a
+ * lifetime, and an invented lifetime violates the no-inference principle.
+ *
+ * Because the decision is made BEFORE dispatch, a 401 from the Copilot base URL
+ * always means the credential is genuinely dead rather than "the token expired
+ * mid-flight" — which is what lets auth failures stay non-retryable
+ * (Requirement 5.8).
+ * @param api - the cached token, or `undefined` when there is none.
+ * @param now - current time in epoch milliseconds.
+ * @param marginMs - exchange this long before expiry.
+ * @returns true when an exchange is due.
+ */
+declare function shouldExchange(api: CopilotTokenExpiry | undefined, now: number, marginMs?: number): boolean;
+//#endregion
+//#region src/common/http.d.ts
+/** Shared HTTP settings. Every field is optional and every default is a bound, not "unlimited". */
+interface CopilotHttpOptions {
+  /** Cancellation for the request and for the body read. */
+  readonly signal?: AbortSignal;
+  /** HTTP implementation, for tests and non-browser runtimes. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Deadline for one request. Defaults to {@link COPILOT_DEFAULT_REQUEST_TIMEOUT_MS}. */
+  readonly requestTimeoutMs?: number;
+  /** Maximum response bytes. Defaults to {@link COPILOT_DEFAULT_MAX_RESPONSE_BYTES}. */
+  readonly maxResponseBytes?: number;
+  /** Maximum response chunks. Defaults to {@link COPILOT_DEFAULT_MAX_RESPONSE_CHUNKS}. */
+  readonly maxResponseChunks?: number;
+  /**
+   * Permit an `http:` origin for a trusted local test endpoint. Defaults to false.
+   *
+   * A separate, explicitly enabled option rather than a lenient default, because
+   * cleartext HTTP here carries a bearer token (Requirement 2.2).
+   */
+  readonly allowInsecureIssuer?: boolean;
+}
+//#endregion
+//#region src/exchange.d.ts
+/** GitHub's API base, where the token-exchange surface lives. */
+declare const DEFAULT_GITHUB_API_BASE_URL = "https://api.github.com";
+/** Path of the token-exchange surface. */
+declare const COPILOT_TOKEN_EXCHANGE_PATH = "/copilot_internal/v2/token";
+/** Settings for one token exchange. Every field is optional; every default is a bound. */
+interface CopilotExchangeOptions extends CopilotHttpOptions {
+  /** Overrides {@link DEFAULT_GITHUB_API_BASE_URL}; pinned as its own origin. */
+  readonly githubApiBaseUrl?: string;
+  /** Overrides for the two mandatory editor headers. */
+  readonly editorHeaders?: CopilotEditorHeaders;
+  /**
+   * Further secret values to strike out of any body this exchange retains,
+   * beyond the credential it sends itself.
+   *
+   * Requirement 13.7 is stated over BOTH tokens, not just the one a given request
+   * carries, and an exchange knows only its own. The remaining value — the
+   * `Copilot_Api_Token` currently held — reaches this path from
+   * {@link createCopilotTokenCache}, which is the one component holding both at
+   * once. Without it, a body echoing the live API token back would travel into
+   * `cause` intact, because the redaction here would be looking for the wrong
+   * string.
+   */
+  readonly additionalSecrets?: readonly string[];
+}
+/**
+ * The result of one `Copilot_Token_Exchange`, held in process memory only.
+ *
+ * Structurally satisfies `CopilotTokenExpiry` from `./auth.ts`, so `shouldExchange`
+ * accepts one of these with no conversion.
+ */
+interface CopilotApiToken {
+  /** Bearer token for the Copilot API base. Short-lived, ~25 minutes. */
+  readonly token: string;
+  /** Expiry instant in epoch MILLISECONDS, derived from `expires_at` (seconds). */
+  readonly expiresAtMs: number;
+  /** The endpoint's `refresh_in` hint in seconds, when it sent a usable one. ADVISORY. */
+  readonly refreshInSeconds?: number;
+  /**
+   * The endpoint's declared `endpoints.api`, when present.
+   *
+   * MUST NOT be used as a base URL. A server-designated base URL is a redirect
+   * under another name, and Requirements 3.8/7.8 settled that this SDK does not
+   * follow provider-controlled redirection. This field exists so `--status` can
+   * print it and so a configuration drift is visible. See DD-6.
+   */
+  readonly declaredApiEndpoint?: string;
+}
+/**
+ * Exchange a `GitHub_User_Token` for a `Copilot_Api_Token`.
+ *
+ * The long-lived credential is NOT consumed: nothing here writes to a store, and
+ * the persisted value is left exactly as it was (Requirement 3.4).
+ * @param github - the long-lived GitHub user token. Its value never reaches an
+ *   error message, and any occurrence of it in a response body is redacted before
+ *   the body is retained as a cause (Requirement 13.7).
+ * @param options - base URL override, injected fetch, signal, and the read bounds.
+ * @returns the short-lived token plus its expiry and the advisory fields.
+ * @throws AgentSdkError with `COPILOT_ENDPOINT_ORIGIN_INVALID` or
+ *   `COPILOT_REDIRECT_REJECTED`, or {@link CopilotTokenExchangeError} with
+ *   `COPILOT_TENANT_UNSUPPORTED`, `COPILOT_CREDENTIAL_REJECTED`,
+ *   `COPILOT_TOKEN_EXCHANGE_FAILED` or `COPILOT_TOKEN_MALFORMED`, per the
+ *   classification order in the module note.
+ */
+declare function exchangeCopilotToken(github: CopilotGitHubToken, options?: CopilotExchangeOptions): Promise<CopilotApiToken>;
+/**
+ * A cache entry, bound to exactly the credential that produced it.
+ *
+ * The pair `(sourceToken, sourceRevision)` is the whole key: signing in as a
+ * different account invalidates the entry the moment the store returns a
+ * different token value, with no TTL involved and no clock consulted.
+ */
+interface CopilotTokenCacheEntry {
+  /** The token this credential produced. */
+  readonly api: CopilotApiToken;
+  /** The `GitHub_User_Token` value used. Compared with `===`. */
+  readonly sourceToken: string;
+  /** The store revision at read time, or `null` for a store without revisions. */
+  readonly sourceRevision: string | null;
+}
+/**
+ * The process-memory cache in front of {@link exchangeCopilotToken}.
+ *
+ * Owned by an adapter instance, and injectable through the adapter's `tokenCache`
+ * option so several routes sharing one unchanged credential exchange once rather
+ * than once per route.
+ */
+interface CopilotTokenCache {
+  /**
+   * Return a live `Copilot_Api_Token` for this credential, exchanging when due.
+   *
+   * Concurrent calls that all need an exchange are COALESCED into exactly one
+   * in-flight exchange (Requirement 5.4).
+   * @param source - one read of the credential store, revision included.
+   * @param operation - the calling operation; only its signal is read, and it
+   *   bounds THIS caller's wait, never the shared exchange.
+   * @param context - invocation context for the observation record, when there is one.
+   * @returns a token that is live as of the decision moment.
+   */
+  acquire(source: CopilotCredentialSnapshot, operation: CredentialOperationOptions, context?: ModelInvocationContext): Promise<CopilotApiToken>;
+  /** Drop the current entry; used when the API surface rejects a token before its expiry. */
+  invalidate(): void;
+}
+/** Provider name recorded on the credential-operation observation by default. */
+declare const COPILOT_PROVIDER_ID = "copilot";
+/** Settings for {@link createCopilotTokenCache}: the exchange settings, plus a clock. */
+interface CopilotTokenCacheOptions extends CopilotExchangeOptions {
+  /**
+   * Provider name on the observation record. Defaults to {@link COPILOT_PROVIDER_ID}.
+   *
+   * An adapter with a custom `id` passes it here so the record names the provider
+   * the caller configured rather than the family.
+   */
+  readonly providerId?: string;
+  /** Exchange this long before expiry. Defaults to `COPILOT_TOKEN_EXCHANGE_MARGIN_MS`. */
+  readonly marginMs?: number;
+  /**
+   * The clock the exchange decision reads, injectable so a test places `now`
+   * exactly on a boundary instead of waiting for one.
+   */
+  readonly now?: () => number;
+}
+/**
+ * Build a token cache over one set of exchange settings.
+ *
+ * ## The mistake this is written to avoid
+ *
+ * The shared exchange gets its OWN `AbortController` plus its own deadline, and
+ * NEVER any single caller's signal. Were the caller's signal handed to it, the
+ * first caller to abort would cancel the exchange every other caller is waiting
+ * on, and those callers would fail for a reason that has nothing to do with them.
+ * Instead each caller — the one that started the exchange included — races the
+ * shared promise against its OWN signal: an aborted caller leaves, and the
+ * exchange still completes for everyone else (Property 18).
+ *
+ * The observation therefore counts exchanges actually DISPATCHED rather than
+ * callers served, which is what makes the coalescing observable instead of merely
+ * claimed (Property 52). It is recorded with the `'refresh'` operation name: that
+ * parameter's union is closed at `'resolve' | 'refresh' | 'login'`, widening it
+ * would change a public type of `provider-http`, and Requirement 18.4 forbids
+ * that — see DD-7.
+ *
+ * ## Two paths deliberately absent
+ *
+ * There is no revision-conflict recovery, unlike `provider-codex`. That path
+ * exists there because a Codex refresh token rotates and is single-use, so a lost
+ * race destroys a credential. A `GitHub_User_Token` does not rotate and an
+ * exchange does not consume it, so two racing processes simply exchange twice —
+ * and a branch no situation reaches is a branch nothing verifies (DD-8).
+ *
+ * Nothing here writes to a store. The `Copilot_Api_Token` is never persisted: it
+ * lives ~25 minutes, so persisting it would add a second secret on disk, a second
+ * write path, and a new state to reason about, to save one request inside a
+ * 25-minute window (DD-9, Requirement 3.3).
+ *
+ * A failure is returned to every waiting caller as-is and never retried here — an
+ * endpoint that rejected the credential will reject it again, and this layer has
+ * no way to change that (Requirement 5.8, Property 19).
+ * @param options - exchange settings, the observation provider name, the margin
+ *   and the clock. `options.signal` is deliberately IGNORED for the exchange
+ *   itself; per-caller cancellation travels through `operation.signal`.
+ * @returns a cache over a single credential slot.
+ */
+declare function createCopilotTokenCache(options?: CopilotTokenCacheOptions): CopilotTokenCache;
+//#endregion
+//#region src/adapter.d.ts
+/** Registry id, provider family, and observation label when the caller sets none. */
+declare const COPILOT_ROUTE_ID = "copilot";
+/** Display name reported by the adapter and the plugin. */
+declare const COPILOT_DISPLAY_NAME = "GitHub Copilot";
+/**
+ * Everything a Copilot route can be configured with.
+ *
+ * The `authStore` is REQUIRED and injected: paths, the filesystem and the
+ * environment belong to `Copilot_Node_Auth`, so a Universal package cannot supply
+ * a default here (Requirement 6.1). Every other field is optional, and an absent
+ * one is spread away rather than passed as `undefined` — see
+ * {@link copilotAdapter}.
+ */
+interface CopilotProviderOptions {
+  /**
+   * Where the credentials live: the compare-and-swap variant.
+   *
+   * This is the main path. {@link copilotAdapter} also accepts the read/write
+   * variant through an overload; `copilotPlugin` does not, because transactional
+   * registration and a store with no revisions are a poor pair.
+   */
+  readonly authStore: CopilotCredentialStore;
+  /** Endpoint base; defaults to `COPILOT_BASE_URL`. */
+  readonly baseUrl?: string;
+  /**
+   * Permit a cleartext `http:` base URL.
+   *
+   * Explicit opt-in rather than a lenient default, because every request to this
+   * surface carries a bearer token (Requirement 2.2).
+   */
+  readonly allowInsecureHttp?: boolean;
+  /** Overrides for the two mandatory editor headers (Requirement 2.4). */
+  readonly editorHeaders?: CopilotEditorHeaders;
+  /** Pin an endpoint for specific model ids, overriding the router (Requirement 9.6). */
+  readonly endpointOverrides?: Readonly<Record<string, CopilotEndpoint>>;
+  /**
+   * Extra model-id prefixes treated as `/responses`-capable when the catalog says
+   * nothing.
+   *
+   * ADDS to `COPILOT_RESPONSES_MODEL_PREFIXES`; it cannot replace it, so an
+   * override never silently drops a prefix this package ships.
+   */
+  readonly responsesModelPrefixes?: readonly string[];
+  /** Synchronous, best-effort observer of every endpoint decision (Requirement 9.8). */
+  readonly onEndpointDecision?: (decision: CopilotEndpointDecision) => void;
+  /**
+   * A token cache shared with other routes.
+   *
+   * Pass one cache to several routes backed by the SAME credential and they
+   * exchange once between them instead of once each.
+   */
+  readonly tokenCache?: CopilotTokenCache;
+  /** Exchange this long before the API token expires. */
+  readonly exchangeMarginMs?: number;
+  /** GitHub API base, where the token exchange lives; pinned as its own origin. */
+  readonly githubApiBaseUrl?: string;
+  /**
+   * The model catalog.
+   *
+   * Left undefined, the adapter DISCOVERS it: which models an account may call
+   * depends on its plan, its organisation policy and the editor identity the
+   * request presents, so no hardcoded list is right for two accounts at once
+   * (Requirement 8.1).
+   */
+  readonly models?: readonly ProviderCatalogModel[];
+  /** Maximum raw catalog bytes. */
+  readonly maxCatalogBytes?: number;
+  /** Maximum catalog entries; more than this is a malformed catalog, not a truncated one. */
+  readonly maxCatalogModels?: number;
+  /** Maximum catalog response chunks. */
+  readonly maxCatalogChunks?: number;
+  /** Catalog request deadline. */
+  readonly catalogTimeoutMs?: number;
+  /** How long a discovered catalog stays fresh. */
+  readonly catalogTtlMs?: number;
+  /** How long a stale catalog may still be served while a refresh runs. */
+  readonly catalogStaleTtlMs?: number;
+  /** How long to wait before retrying discovery after it failed. */
+  readonly catalogFailureBackoffMs?: number;
+  /** Dialect overrides, merged shallowly over `COPILOT_DEFAULT_DIALECT`. */
+  readonly dialect?: Partial<CopilotDialect>;
+  /** Output cap when neither caller nor catalog names one. */
+  readonly defaultMaxTokens?: number;
+  /** Context capacity assumed for an uncatalogued model. */
+  readonly defaultContextWindow?: number;
+  /** Idle bound while a stream read is outstanding. */
+  readonly streamIdleTimeoutMs?: number;
+  /** Deadline for one request. */
+  readonly requestTimeoutMs?: number;
+  /** Maximum serialized request bytes. */
+  readonly maxRequestBytes?: number;
+  /** Maximum response bytes. */
+  readonly maxResponseBytes?: number;
+  /** Maximum response chunks. */
+  readonly maxResponseChunks?: number;
+  /** Maximum SSE events in one stream. */
+  readonly maxSseEvents?: number;
+  /** Maximum characters in one SSE event. */
+  readonly maxSseEventChars?: number;
+  /** Maximum bytes read from a non-success response (Requirement 13.6). */
+  readonly maxErrorBodyBytes?: number;
+  /** Deadline granted to {@link requestLogger} before the request proceeds anyway. */
+  readonly requestLoggerTimeoutMs?: number;
+  /** Retry policy this route owns (Requirement 7.7). */
+  readonly retryPolicy?: RetryPolicyConfig;
+  /**
+   * Exact wire-request observer.
+   *
+   * BEST-EFFORT: credentials are redacted by the transport, the logger's deadline
+   * is `requestLoggerTimeoutMs`, and a logger that overruns or throws does not
+   * stop the request (Requirement 14.5).
+   */
+  readonly requestLogger?: ProviderRequestLogger;
+  /** HTTP implementation, for tests and non-browser runtimes. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Registry id; defaults to {@link COPILOT_ROUTE_ID}. */
+  readonly id?: string;
+  /** Routes the plugin installs; defaults to `[id]`. */
+  readonly routes?: readonly string[];
+  /** Default model; a string form requires exactly one route (Requirement 7.5). */
+  readonly defaultModel?: string | ModelTarget;
+}
+/**
+ * The same options against the read/write store variant.
+ *
+ * Kept for symmetry with `provider-codex` and with the two store contracts
+ * (Requirement 7.3). It has no revisions, so a commit cannot be
+ * compare-and-swapped — which costs nothing here, since nothing on the Copilot
+ * credential path writes.
+ */
+interface CopilotLegacyProviderOptions extends Omit<CopilotProviderOptions, 'authStore'> {
+  /** Where the credentials live: the read/write variant. */
+  readonly authStore: CopilotAuthStore;
+}
+/**
+ * Create a Copilot adapter.
+ *
+ * Both store variants are accepted, and the variant is chosen by INSPECTING THE
+ * MARKER through `captureCopilotStore` — which reads data properties only and
+ * performs no storage I/O, so building a provider cannot run a line of the
+ * caller's code (Requirement 7.3).
+ * @param options - credential store, endpoint, catalog, dialect and transport settings.
+ * @returns the adapter, ready to register.
+ * @throws AgentSdkError with `CREDENTIAL_STORE_INVALID` when `authStore` is
+ *   neither store variant, or `COPILOT_ENDPOINT_OVERRIDE_INVALID` when
+ *   `endpointOverrides` pins an endpoint that does not exist.
+ */
+declare function copilotAdapter(options: CopilotProviderOptions): HttpModelAdapter;
+declare function copilotAdapter(options: CopilotLegacyProviderOptions): HttpModelAdapter;
+/** Plugin options; the CAS store variant only. */
+type CopilotPluginOptions = CopilotProviderOptions;
+/**
+ * The transactional plugin for installing the Copilot provider.
+ *
+ * Composition follows `codexPlugin`: `id` defaults to {@link COPILOT_ROUTE_ID},
+ * `family` is `'copilot'`, `routes` defaults to `[id]`, and a string
+ * `defaultModel` requires exactly one route so the model target's provider can be
+ * inferred (Requirements 7.4, 7.5).
+ *
+ * One difference from Codex: there is no overload per store variant. The
+ * compare-and-swap store is the main path here, the read/write variant exists for
+ * symmetry, and {@link copilotAdapter} is where it is accepted (Requirement 6.2).
+ * The marker is checked at construction rather than at setup so a wrong store is
+ * reported while the runtime is being composed, not on the first generation.
+ * @param options - the same options {@link copilotAdapter} takes, CAS store only.
+ * @returns a composable plugin registering one Copilot adapter.
+ * @throws TypeError when `authStore` is not the compare-and-swap variant, or when
+ *   a string `defaultModel` is paired with anything but exactly one route.
+ */
+declare function copilotPlugin(options: CopilotPluginOptions): ComposableModelProviderPlugin & {
+  readonly family: 'copilot';
+};
+//#endregion
+//#region src/common/error-codes.d.ts
+/**
+ * The Copilot error codes, in the leaf layer so the shared HTTP modules can reach
+ * them.
+ *
+ * The taxonomy BELONGS to `../errors.ts` — that module is the public door, and it
+ * re-exports everything here. The definition lives one layer down for a structural
+ * reason: `common/` is a leaf, and `common/http.ts` needs
+ * `ENDPOINT_ORIGIN_INVALID` and `COPILOT_REDIRECT_REJECTED` to throw. Importing
+ * them from a root module would make `common/` depend on the root while the root
+ * already depends on `common/`, which is the source-ownership cycle the repo's
+ * package-graph check forbids. Duplicating the two strings instead would be worse:
+ * a code that exists in two places is a code that can disagree with itself.
+ *
+ * Read `../errors.ts` for the taxonomy's rationale, including the three situations
+ * that deliberately get an EXISTING SDK code rather than a Copilot one.
+ *
+ * @module ai-agent-sdk/providers/copilot/error-codes
+ */
+/**
+ * Stable codes for the failures that are specific to Copilot.
+ *
+ * Frozen, and flat strings rather than a TS enum, for the same reason the core
+ * taxonomy is: a consumer routes on the value, and the value has to survive
+ * serialization into a log line.
+ */
+declare const COPILOT_ERROR_CODES: Readonly<{
+  /** The token-exchange surface rejected the credential: a PAT, or a non-allowlisted OAuth App. */
+  readonly CREDENTIAL_REJECTED: 'COPILOT_CREDENTIAL_REJECTED';
+  /** Token exchange failed for a reason that is not the credential. */
+  readonly TOKEN_EXCHANGE_FAILED: 'COPILOT_TOKEN_EXCHANGE_FAILED';
+  /** The token-exchange response carried no readable `expires_at`, or was not JSON. */
+  readonly TOKEN_MALFORMED: 'COPILOT_TOKEN_MALFORMED';
+  /** A `*.ghe.com` data-residency tenant has no token-exchange surface. */
+  readonly TENANT_UNSUPPORTED: 'COPILOT_TENANT_UNSUPPORTED';
+  /** The endpoint rejected the request for missing `Editor_Headers`. */
+  readonly EDITOR_HEADERS_MISSING: 'COPILOT_EDITOR_HEADERS_MISSING';
+  /** The target URL is not on the same origin as the configured issuer/base URL. */
+  readonly ENDPOINT_ORIGIN_INVALID: 'COPILOT_ENDPOINT_ORIGIN_INVALID';
+  /** The response was a redirect; this SDK does not follow it. */
+  readonly REDIRECT_REJECTED: 'COPILOT_REDIRECT_REJECTED';
+  /** Device flow: the user denied the request. */
+  readonly DEVICE_LOGIN_DENIED: 'COPILOT_DEVICE_LOGIN_DENIED';
+  /** Device flow: the code expired server-side. */
+  readonly DEVICE_LOGIN_EXPIRED: 'COPILOT_DEVICE_LOGIN_EXPIRED';
+  /** Device flow: the absolute 15-minute bound passed without approval. */
+  readonly DEVICE_LOGIN_TIMEOUT: 'COPILOT_DEVICE_LOGIN_TIMEOUT';
+  /** Device flow: failed for any other reason. */
+  readonly DEVICE_LOGIN_FAILED: 'COPILOT_DEVICE_LOGIN_FAILED';
+  /** A credential commit found a revision other than the expected one. */
+  readonly CREDENTIAL_REVISION_CONFLICT: 'COPILOT_CREDENTIAL_REVISION_CONFLICT';
+  /** The `/models` response was the wrong shape at the structural level. */
+  readonly CATALOG_MALFORMED: 'COPILOT_CATALOG_MALFORMED';
+  /** `endpointOverrides` pinned a model to an endpoint that does not exist. */
+  readonly ENDPOINT_OVERRIDE_INVALID: 'COPILOT_ENDPOINT_OVERRIDE_INVALID';
+}>;
+/** One of the codes {@link COPILOT_ERROR_CODES} owns. */
+type CopilotErrorCode = (typeof COPILOT_ERROR_CODES)[keyof typeof COPILOT_ERROR_CODES];
+//#endregion
+//#region src/errors.d.ts
+/** A sanitized cause plus the message it is allowed to travel with. */
+interface CopilotCredentialFailure {
+  /** SDK-authored text. Never carries a token value, because nothing interpolates one in. */
+  readonly message: string;
+  /** The cause, reduced to serializable facts; `undefined` when there was none. */
+  readonly cause: SafeErrorRecord | undefined;
+}
+/**
+ * Build the inputs for an error on the Copilot credential path.
+ *
+ * This is the ONLY door: {@link CopilotTokenExchangeError} and
+ * {@link CopilotDeviceLoginError} take a {@link CopilotCredentialFailure} rather
+ * than a raw `cause`, so there is no code path that can attach an unfiltered
+ * value to a credential-path error. `message` is SDK-authored text; a
+ * `GitHub_User_Token` or a `Copilot_Api_Token` is never interpolated into it, and
+ * response bodies reach `cause` only after the bounded read has replaced every
+ * occurrence of the tokens held in memory with `[REDACTED]` (Requirement 13.7).
+ * @param message - SDK-authored, actionable text. No token values.
+ * @param cause - the caught value, if any; filtered before it is retained.
+ * @returns the sanitized pair an error class accepts.
+ */
+declare function credentialFailure(message: string, cause?: unknown): CopilotCredentialFailure;
+/** Whether a token-exchange failure can ever succeed on a retry. */
+type CopilotTokenExchangeFailureKind = 'permanent' | 'transient';
+/**
+ * A `Copilot_Token_Exchange` that did not produce a token.
+ *
+ * `kind` exists because `code` alone does not answer the only question a caller
+ * has to answer next: `TOKEN_EXCHANGE_FAILED` covers both a 5xx worth waiting out
+ * and a 4xx that will fail identically forever.
+ */
+declare class CopilotTokenExchangeError extends AgentSdkError {
+  /** Retry classification for this failure. */
+  readonly kind: CopilotTokenExchangeFailureKind;
+  /**
+   * @param failure - message and filtered cause from {@link credentialFailure}.
+   * @param code - the Copilot code for this row of the classification table.
+   * @param kind - whether a retry could ever succeed.
+   */
+  constructor(failure: CopilotCredentialFailure, code: CopilotErrorCode, kind: CopilotTokenExchangeFailureKind);
+}
+/** Why a device login ended without a token. */
+type CopilotDeviceLoginReason = 'denied' | 'expired' | 'timeout' | 'aborted' | 'failed';
+/**
+ * A device login that ended without a `GitHub_User_Token`.
+ *
+ * The `code` is derived from `reason` rather than passed in, so the two can never
+ * disagree — a caller reading `code` and a caller reading `reason` always see the
+ * same outcome.
+ */
+declare class CopilotDeviceLoginError extends AgentSdkError {
+  /** The distinguishable reason the flow ended. */
+  readonly reason: CopilotDeviceLoginReason;
+  /**
+   * @param failure - message and filtered cause from {@link credentialFailure}.
+   * @param reason - the outcome; decides the `code`, with `aborted` mapping to
+   *   {@link MODEL_ERROR_CODES.ABORTED} rather than a Copilot-specific code.
+   */
+  constructor(failure: CopilotCredentialFailure, reason: CopilotDeviceLoginReason);
+}
+//#endregion
+//#region src/oauth.d.ts
+/** GitHub's OAuth issuer. */
+declare const DEFAULT_COPILOT_OAUTH_ISSUER = "https://github.com";
+/**
+ * Default OAuth client id. Public, not a secret.
+ *
+ * This is the client id published in GitHub's own editor-plugin sources (the
+ * value `copilot.vim` and the other Copilot editor integrations ship in the
+ * clear), which is why it is on the allowlist that
+ * `copilot_internal/v2/token` checks. Sending it means this SDK signs in AS that
+ * editor client. See the module note for why that makes it a named option
+ * instead of a hidden constant.
+ *
+ * ⚠ UNVERIFIED against a live account. Recorded 2026-09-10 from public editor
+ * integration sources only; no sign-in against a real Copilot account has
+ * confirmed THIS client id.
+ *
+ * The 2026-09-10 live run that confirmed the two editor headers did NOT confirm
+ * this value, and could not: it was handed an existing `ghu_` user-to-server token
+ * out of band, so it exercised the EXCHANGE (which answered 200 for that token)
+ * while never running the device flow that would put this `client_id` on the wire.
+ * What that run does establish is the shape of the claim still outstanding — the
+ * exchange endpoint and the allowlist check are live and reachable, and the only
+ * untested link is whether they accept a token minted by this particular app.
+ *
+ * TODO(copilot-identity): confirm on a real Copilot account, then replace this
+ * warning with the confirmation date. To confirm: run the device flow against
+ * `https://github.com/login/device/code` with this `client_id` and
+ * `scope=read:user`, approve it on a Copilot-enabled account, then exchange the
+ * resulting user token at `GET https://api.github.com/copilot_internal/v2/token`.
+ * The client id is confirmed when that exchange returns a Copilot token rather
+ * than 401/403. A non-allowlisted client id fails at the exchange, not at
+ * sign-in, so the device flow succeeding on its own proves nothing — and equally,
+ * an exchange that succeeds for a token this flow did not mint proves nothing
+ * about this constant.
+ */
+declare const COPILOT_OAUTH_CLIENT_ID = "Iv1.b507a08c87ecfe98";
+/** Requested scope; enough to exchange a token and read identity, no more. */
+declare const COPILOT_OAUTH_SCOPE = "read:user";
+/**
+ * The absolute ceiling on one device login, INDEPENDENT of the server's
+ * `expires_in`.
+ *
+ * `expires_in` is honoured when it is shorter — there is no point polling a code
+ * the server has already retired. It is not honoured when it is longer: a server
+ * that answers `expires_in: 86400` would otherwise hang a CLI for a day, and this
+ * SDK is not the right place to hold that terminal hostage (Requirement 4.3).
+ */
+declare const COPILOT_DEVICE_CODE_MAX_WAIT_MS: number;
+/** Poll interval used when the device-code response states none. */
+declare const COPILOT_DEFAULT_POLL_INTERVAL_SECONDS = 5;
+/**
+ * Seconds added on every `slow_down`, per RFC 8628 §3.5.
+ *
+ * The increment is what makes the wait STRICTLY increase even when the server
+ * repeats `slow_down` without a new `interval`. Without it, a server that only
+ * ever says "slow down" would be polled at exactly the rate it just objected to.
+ */
+declare const COPILOT_SLOW_DOWN_INCREMENT_SECONDS = 5;
+/**
+ * The warning shown beside the user code, worded exactly as the Codex device
+ * prompt words it.
+ *
+ * A device code is a bearer of authorization that the user types into a page they
+ * navigated to themselves. The one attack that works is getting somebody to type
+ * an attacker's code, so the prompt has to say so; and it lives here rather than
+ * in the CLI so every front end that renders a Copilot prompt renders the same
+ * sentence.
+ */
+declare const COPILOT_DEVICE_LOGIN_WARNING = "Only continue if YOU started this login. If someone sent you this code, stop.";
+/**
+ * The scheduler the poll loop waits on, injectable so no test waits real time.
+ *
+ * `now` travels with the timer rather than sitting in a second option, because
+ * the two are read together on every iteration: a fake timer that advances
+ * pending callbacks while `Date.now()` stands still would let a test satisfy the
+ * 15-minute bound by accident, in either direction. Handing both through one
+ * object makes "virtual clock" a single substitution (Properties 11, 12, 14).
+ */
+interface CopilotTimer {
+  /** Schedule `handler` after `ms`; returns whatever handle `clear` accepts. */
+  readonly setTimeout: (handler: () => void, ms: number) => unknown;
+  /** Cancel a handle from {@link CopilotTimer.setTimeout}. */
+  readonly clearTimeout: (handle: unknown) => void;
+  /** Current time in epoch milliseconds. */
+  readonly now: () => number;
+}
+/** The real scheduler: `setTimeout`, `clearTimeout` and `Date.now`. */
+declare const DEFAULT_COPILOT_TIMER: CopilotTimer;
+/**
+ * Settings for both device-flow legs.
+ *
+ * Extends {@link CopilotHttpOptions}, so the issuer pin, the deadline and the two
+ * read bounds are the same ones every other Copilot call site uses
+ * (Requirement 4.7). `oauthIssuer` is named rather than called `issuer` because
+ * this package pins THREE origins independently and the field name is what says
+ * which one is being set.
+ */
+interface CopilotOAuthOptions extends CopilotHttpOptions {
+  /** OAuth issuer base URL; defaults to {@link DEFAULT_COPILOT_OAUTH_ISSUER}. */
+  readonly oauthIssuer?: string;
+  /** OAuth client id; defaults to {@link COPILOT_OAUTH_CLIENT_ID}. */
+  readonly clientId?: string;
+  /** Requested scope; defaults to {@link COPILOT_OAUTH_SCOPE}. */
+  readonly scope?: string;
+  /** Scheduler for the poll wait; defaults to {@link DEFAULT_COPILOT_TIMER}. */
+  readonly timer?: CopilotTimer;
+}
+/** A pending device authorization the user has to approve. */
+interface CopilotDeviceCode {
+  /** URL to open in a browser. Displayed to the user; never fetched by this SDK. */
+  readonly verificationUrl: string;
+  /** One-time code the user types there. */
+  readonly userCode: string;
+  /** Opaque handle this SDK polls with. Never shown to the user. */
+  readonly deviceCode: string;
+  /** Seconds to wait between polls, as the server asked. */
+  readonly intervalSeconds: number;
+  /** Seconds until the server retires the code. */
+  readonly expiresInSeconds: number;
+}
+/** Progress reported while a device login runs. */
+interface CopilotLoginProgress {
+  /** The code is ready; show it, with {@link COPILOT_DEVICE_LOGIN_WARNING}. */
+  readonly onPrompt?: (code: CopilotDeviceCode) => void;
+  /** Called before each poll, with the interval currently in effect. */
+  readonly onPoll?: (elapsedMs: number, intervalSeconds: number) => void;
+}
+/** Result of a completed device login. */
+interface CopilotLoginResult {
+  /** Where the credential was written. Always present. */
+  readonly location: string;
+  /** GitHub login, when the endpoint discloses one. */
+  readonly login: string | undefined;
+  /** Numeric account id, when the endpoint discloses one. */
+  readonly accountId: number | undefined;
+  /** Granted scope, when the endpoint discloses it. */
+  readonly scope: string | undefined;
+}
+/**
+ * Start a device authorization.
+ *
+ * `Accept: application/json` is set here as well as on the token leg. It is
+ * load-bearing on the token leg (see {@link pollForCopilotToken}) and harmless
+ * here, and setting it on both keeps the pair from drifting into "one of the two
+ * legs parses JSON".
+ * @param options - issuer, client id, scope, cancellation and read bounds.
+ * @returns the code, the URL and the timings to show the user.
+ * @throws CopilotDeviceLoginError with `reason: 'aborted'` when the caller's
+ *   signal aborts, or `reason: 'failed'` when the endpoint answers with anything
+ *   other than a usable device authorization.
+ */
+declare function requestCopilotDeviceCode(options?: CopilotOAuthOptions): Promise<CopilotDeviceCode>;
+/**
+ * Run a full device login and persist the resulting `GitHub_User_Token`.
+ *
+ * The store is read BEFORE the flow starts, so the commit carries the revision
+ * that was current when the login began and a concurrent login loses the race
+ * loudly instead of silently overwriting. Nothing else is written: the
+ * `GitHub_User_Token` does not rotate, so this is the only write in the whole
+ * Copilot credential path.
+ * @param store - the credential store to write, in either variant.
+ * @param options - issuer, client id, scope, cancellation, bounds and timer.
+ * @param progress - prompt and poll notifications for a CLI to render.
+ * @returns the store location plus whatever identity the endpoint disclosed.
+ * @throws CopilotDeviceLoginError with `reason` distinguishing `denied`,
+ *   `expired`, `timeout`, `aborted` and `failed`.
+ */
+declare function runCopilotDeviceLogin(store: CopilotCredentialStore, options?: CopilotOAuthOptions, progress?: CopilotLoginProgress): Promise<CopilotLoginResult>;
+declare function runCopilotDeviceLogin(store: CopilotAuthStore, options?: CopilotOAuthOptions, progress?: CopilotLoginProgress): Promise<CopilotLoginResult>;
+//#endregion
+export { COPILOT_BASE_URL, COPILOT_CATALOG_PATH, COPILOT_DEFAULT_CATALOG_TIMEOUT_MS, COPILOT_DEFAULT_DIALECT, COPILOT_DEFAULT_MAX_CATALOG_BYTES, COPILOT_DEFAULT_MAX_CATALOG_CHUNKS, COPILOT_DEFAULT_MAX_CATALOG_MODELS, COPILOT_DEFAULT_POLL_INTERVAL_SECONDS, COPILOT_DEVICE_CODE_MAX_WAIT_MS, COPILOT_DEVICE_LOGIN_WARNING, COPILOT_DISPLAY_NAME, COPILOT_DUAL_PROTOCOL_ID, COPILOT_EDITOR_PLUGIN_VERSION, COPILOT_EDITOR_VERSION, COPILOT_ERROR_CODES, COPILOT_LOGIN_COMMAND, COPILOT_OAUTH_CLIENT_ID, COPILOT_OAUTH_SCOPE, COPILOT_PROVIDER_ID, COPILOT_RESPONSES_MODEL_PREFIXES, COPILOT_ROUTE_ID, COPILOT_SLOW_DOWN_INCREMENT_SECONDS, COPILOT_TOKEN_EXCHANGE_MARGIN_MS, COPILOT_TOKEN_EXCHANGE_PATH, type ChatCompletionsProtocolLike, type CopilotAccountIdentity, type CopilotApiToken, type CopilotAuthFile, type CopilotAuthStore, type CopilotCatalogLimits, type CopilotCatalogOptions, type CopilotCatalogSnapshot, type CopilotCredentialFailure, type CopilotCredentialSnapshot, type CopilotCredentialStore, type CopilotDeviceCode, CopilotDeviceLoginError, type CopilotDeviceLoginReason, type CopilotDialect, type CopilotDualProtocolOptions, type CopilotEditorHeaders, type CopilotEmbeddingModel, type CopilotEndpoint, type CopilotEndpointDecision, type CopilotEndpointRouter, type CopilotEndpointRouterOptions, type CopilotErrorCode, type CopilotExchangeOptions, type CopilotGenerationModel, type CopilotGitHubToken, type CopilotLegacyProviderOptions, type CopilotLoginProgress, type CopilotLoginResult, type CopilotOAuthOptions, type CopilotOmitReason, type CopilotOmittedModel, type CopilotPluginOptions, type CopilotProviderOptions, type CopilotSubProtocol, type CopilotTimer, type CopilotTokenCache, type CopilotTokenCacheEntry, type CopilotTokenCacheOptions, CopilotTokenExchangeError, type CopilotTokenExchangeFailureKind, type CopilotTokenExpiry, DEFAULT_COPILOT_OAUTH_ISSUER, DEFAULT_COPILOT_TIMER, DEFAULT_GITHUB_API_BASE_URL, type ResponsesProtocolLike, copilotAdapter, copilotCatalogCacheOptions, copilotDualProtocol, copilotPlugin, createCopilotEndpointRouter, createCopilotTokenCache, credentialFailure, discoverCopilotModels, exchangeCopilotToken, memoryCopilotAuthStore, memoryCopilotCredentialStore, partitionCopilotCatalog, requestCopilotDeviceCode, requireGitHubToken, resolveCopilotCatalogLimits, runCopilotDeviceLogin, shouldExchange, toChatCompletionsDialect, toResponsesDialect };
+//# sourceMappingURL=index.d.ts.map