Theia API Documentation v1.77.0
    Preparing search index...

    Framework API for reading and writing AI-related (ai-features.*) preferences.

    AiConfigurationService wraps the core PreferenceService and is the intended extension point for adopters and extensions that configure AI features: prefer it over talking to PreferenceService directly for ai-features.* keys. Routing all AI configuration through this seam keeps consumers insulated from future changes to how AI preferences are stored.

    Reads (get, inspect) are workspace-trust-aware: workspace and folder scope values are suppressed while the workspace is untrusted (failing closed until the trust state resolves), matching how AI features read preferences today. Session values (set via --session-preference) apply regardless of trust. Writes (set, update) are never gated by trust.

    interface AiConfigurationService {
        onDidChange: Event<AiConfigurationChange>;
        ready: Promise<void>;
        get<T>(key: string, defaultValue?: T, resourceUri?: string): T | undefined;
        inspect<T extends JSONValue>(
            key: string,
            resourceUri?: string,
        ): AiConfigurationInspection<T> | undefined;
        set(
            key: string,
            value: unknown,
            scope: PreferenceScope,
            resourceUri?: string,
        ): Promise<void>;
        update(key: string, value: unknown, resourceUri?: string): Promise<void>;
    }

    Implemented by

    Index

    Fires when a ai-features.* preference changes or when the workspace-trust state transitions (which can change the effective value of trust-gated keys). The effective value is not carried on the event; listeners re-query it via get/inspect.

    ready: Promise<void>

    Resolves once the underlying preference service and the initial workspace-trust state are ready. Await this before the first read for a deterministic, trust-aware result.

    • Retrieves the effective, trust-aware value for the given preference, including a session value. To change part of an object or a list and write it back, start from AiConfigurationInspection.valueWithoutSession.

      Type Parameters

      • T

      Parameters

      • key: string

        the preference identifier.

      • OptionaldefaultValue: T

        the value to return when no value is stored.

      • OptionalresourceUri: string

        the uri of the resource for which the preference is read.

      Returns T | undefined

    • Writes value to the given scope. Maps to PreferenceService.set.

      Parameters

      • key: string

        the preference identifier.

      • value: unknown

        the new value (must be JSON-serializable). undefined clears the value in the given scope.

      • scope: PreferenceScope

        the scope to write to. For PreferenceScope.Folder a resourceUri is required.

      • OptionalresourceUri: string

        the uri of the resource for which the preference is stored.

      Returns Promise<void>

    • "Smart write": picks the scope so that the effective value becomes value. Maps to PreferenceService.updateValue.

      Parameters

      • key: string

        the preference identifier.

      • value: unknown

        the value to apply (must be JSON-serializable). undefined resets the preference to its default value.

      • OptionalresourceUri: string

        the uri of the resource to which the change applies.

      Returns Promise<void>