@codingame/monaco-vscode-chat-service-override 37.0.0 → 37.1.0

package/vscode/src/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostAuth.d.ts

@@ -0,0 +1,142 @@
+import { fetchAuthorizationServerMetadata } from "@codingame/monaco-vscode-api/vscode/vs/base/common/oauth";
+import { URI } from "@codingame/monaco-vscode-api/vscode/vs/base/common/uri";
+import { type McpOAuthClient, type ModelSelection, type ProtectedResourceMetadata } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/state";
+import { type AgentInfo } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/sessionState";
+import { ServicesAccessor } from "@codingame/monaco-vscode-api/vscode/vs/platform/instantiation/common/instantiation";
+import { ILogService } from "@codingame/monaco-vscode-api/vscode/vs/platform/log/common/log.service";
+import { AuthenticationSession } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/authentication/common/authentication";
+import { IAuthenticationService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/authentication/common/authentication.service";
+/**
+ * Stable identity for an agent-host MCP server, used as the key for
+ * remembered authentication (allowed-server access, account preference and
+ * usage). Agent-host customization ids are **not** stable across reloads —
+ * bare/top-level ids embed the agent-host session id, and synced child ids
+ * embed a per-sync nonce — so keying remembered auth on them orphans the
+ * grant on every reload. Instead we key on the session's host `authority`
+ * plus the server `name` and its resource `url`, all of which are stable
+ * for a given server across sessions and reloads.
+ */
+export declare function agentHostMcpServerId(authority: string, serverName: string, resourceUrl: string): string;
+/**
+ * Whether creating a session with the selected model requires the agent's protected-resource authentication.
+ */
+export declare function modelRequiresAgentAuthentication(agent: AgentInfo | undefined, model: ModelSelection | undefined, allowSignedOutWhenUsable?: boolean): boolean;
+/**
+ * Tracks the last bearer token pushed to a given agent host connection
+ * for each protected resource, so that redundant `authenticate` RPCs can
+ * be suppressed when neither the resource nor the token has changed.
+ *
+ * One instance per connection. Owned by the contribution that drives
+ * authentication for that connection so the cache is dropped naturally
+ * when the connection is disposed.
+ */
+export declare class AgentHostAuthTokenCache {
+    private readonly _completedTokens;
+    private readonly _pendingAuthentications;
+    private readonly _keyGenerations;
+    private _globalGeneration;
+    /**
+     * Forwards a token once per resource/scope pair. Same-token callers share
+     * and await an in-flight authentication.
+     */
+    authenticate(resource: string, scopes: readonly string[] | undefined, token: string, authenticate: () => Promise<unknown>): Promise<boolean>;
+    /**
+     * Clear the cached token for a specific resource/scope pair, a whole resource,
+     * or all resources if no argument is given. Call after a failed `authenticate`
+     * RPC or when the agent host process restarts.
+     */
+    clear(resource?: string, scopes?: readonly string[]): void;
+    private _invalidateKey;
+    private _isCurrentGeneration;
+    private _key;
+}
+/**
+ * Coordinates recovery from authentication challenges for one agent-host connection.
+ */
+export declare class AgentHostAuthenticationRecovery {
+    private readonly _resentTokens;
+    private readonly _pendingRecoveries;
+    clear(): void;
+    recover(accessor: ServicesAccessor, resource: ProtectedResourceMetadata, options: IAgentHostAuthenticationOptions): Promise<void>;
+    private _recover;
+}
+/**
+ * Resolves an authentication session for a protected resource by trying each
+ * authorization server in order. First attempts an exact scope match,
+ * then falls back to finding the session whose scopes are the narrowest
+ * superset of the requested scopes.
+ */
+export declare function resolveSessionForResource(resourceServer: URI, authorizationServers: readonly string[], scopes: readonly string[], authenticationService: IAuthenticationService, logService: ILogService, logPrefix: string): Promise<AuthenticationSession | undefined>;
+export interface IAgentHostAuthenticateRequest {
+    readonly resource: string;
+    readonly scopes?: readonly string[];
+    /** An empty token revokes the credential previously forwarded for this resource and scope set. */
+    readonly token: string;
+    /** The access token's remaining lifetime in seconds, when known. */
+    readonly expiresIn?: number;
+}
+export interface IAgentHostAuthenticationOptions {
+    readonly authTokenCache?: AgentHostAuthTokenCache;
+    readonly logPrefix: string;
+    readonly isCurrent?: () => boolean;
+    readonly authenticate: (request: IAgentHostAuthenticateRequest) => Promise<unknown>;
+}
+export interface IAgentHostMcpAuthenticationOptionsBase {
+    readonly allowInteraction: boolean;
+    readonly authTokenCache?: AgentHostAuthTokenCache;
+    readonly logPrefix: string;
+    readonly mcpServerId: string;
+    readonly mcpServerName: string;
+    readonly mcpServerUrl: string;
+    readonly oauthClient?: McpOAuthClient;
+    readonly scopes: readonly string[];
+    readonly authorizationServerMetadataFetcher?: typeof fetchAuthorizationServerMetadata;
+    /**
+     * Identifies the agent host backing this MCP server so remembered-auth
+     * entries can be surfaced in their own section of the "Manage Trusted MCP
+     * Servers" picker. When set, the resolved host label (via
+     * {@link ILabelService.getHostLabel}) is recorded on the allowed-server
+     * entry. Omit for non-agent-host callers.
+     */
+    readonly agentHost?: {
+        readonly scheme: string;
+        readonly authority: string;
+    };
+    readonly authenticate: (request: IAgentHostAuthenticateRequest) => Promise<unknown>;
+}
+/**
+ * Resolves and forwards bearer tokens for the protected resources declared by
+ * the agents currently published from an agent host.
+ */
+export declare function authenticateProtectedResources(accessor: ServicesAccessor, agents: readonly AgentInfo[], options: IAgentHostAuthenticationOptions): Promise<void>;
+export declare function authenticateAgentProtectedResourcesWithToken(agents: readonly AgentInfo[], token: string, options: Pick<IAgentHostAuthenticationOptions, "authTokenCache" | "authenticate" | "isCurrent">): Promise<void>;
+export declare function authenticateProtectedResourcesWithToken(protectedResources: readonly ProtectedResourceMetadata[], token: string, options: Pick<IAgentHostAuthenticationOptions, "authTokenCache" | "authenticate" | "isCurrent">): Promise<void>;
+/**
+ * Reconciles resources backed by an authentication session that was explicitly
+ * removed.
+ *
+ * A removal event proves the provider is live and managing its sessions, which
+ * is what makes an empty resolution trustworthy here -- unlike the polling path,
+ * where "no token" cannot be distinguished from "not loaded yet". It does not,
+ * however, prove the credential is gone: a provider may host several accounts,
+ * and signing out of one leaves the others usable. Re-resolving keeps a partial
+ * sign-out from revoking a credential the host still needs, which would restart
+ * provider clients and move the Claude proxy port for no reason.
+ *
+ * Only resources the removed sessions could have satisfied are reconciled. One
+ * provider commonly serves several resources with different scope sets (GitHub
+ * serves both the Copilot and repository challenges), and a resource the removed
+ * session never covered must not be re-evaluated against this client's view of
+ * the world -- another client may be the one supplying its credential.
+ */
+export declare function revokeAuthenticationForRemovedSessions(accessor: ServicesAccessor, agents: readonly AgentInfo[], providerId: string, removedSessions: readonly AuthenticationSession[], options: IAgentHostAuthenticationOptions): Promise<void>;
+/**
+ * Resolves and forwards a bearer token for a single protected resource.
+ */
+export declare function authenticateProtectedResource(accessor: ServicesAccessor, resource: ProtectedResourceMetadata, options: IAgentHostAuthenticationOptions): Promise<boolean>;
+/**
+ * Prompts the user to authenticate one of the provided protected resources and
+ * forwards the resulting token to the agent host connection.
+ */
+export declare function resolveAuthenticationInteractively(accessor: ServicesAccessor, protectedResources: readonly ProtectedResourceMetadata[], options: IAgentHostAuthenticationOptions): Promise<boolean>;
+export declare function resolveMcpServerAuthentication(accessor: ServicesAccessor, protectedResource: ProtectedResourceMetadata, options: IAgentHostMcpAuthenticationOptionsBase): Promise<boolean>;