@theia/ai-core 1.74.0-next.0 → 1.74.0-next.15

package/src/common/ai-configuration-service.ts

@@ -0,0 +1,128 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { Event } from '@theia/core';
+import { JSONValue } from '@theia/core/shared/@lumino/coreutils';
+import { PreferenceInspection, PreferenceScope } from '@theia/core/lib/common/preferences';
+
+export const AiConfigurationService = Symbol('AiConfigurationService');
+
+/**
+ * A {@link PreferenceInspection} augmented with a derived, workspace-trust-aware source scope.
+ */
+export interface AiConfigurationInspection<T extends JSONValue = JSONValue> extends PreferenceInspection<T> {
+    /**
+     * The narrowest scope (honoring workspace trust) in which a value is explicitly set, i.e. the
+     * scope that determines the effective {@link PreferenceInspection.value}. Walked in precedence
+     * order `Folder -> Workspace -> User`; `undefined` when only the default value applies. In an
+     * untrusted workspace the folder/workspace scopes are ignored, so `sourceScope` is either
+     * `User` or `undefined`.
+     */
+    sourceScope?: PreferenceScope;
+}
+
+/**
+ * Payload of {@link AiConfigurationService.onDidChange}.
+ */
+export interface AiConfigurationChange {
+    /**
+     * The preference key that changed. When the change is caused by a workspace-trust transition
+     * (which can change the effective value of any trust-gated key) this is `undefined` and
+     * {@link affects} returns `true` for every resource. Listeners tracking a specific key should
+     * re-query the value when `preferenceName` is `undefined` or equals their key.
+     */
+    readonly preferenceName?: string;
+    /**
+     * Tests whether the given resource is affected by the change.
+     * @param resourceUri the uri of the resource to test.
+     */
+    affects(resourceUri?: string): boolean;
+    /**
+     * Tests whether the given preference key is affected by this change, treating a workspace-trust
+     * transition (where {@link preferenceName} is `undefined`) as affecting every trust-gated key.
+     * Prefer this over comparing {@link preferenceName} directly so listeners do not silently miss
+     * trust transitions.
+     * @param preferenceName the preference key to test.
+     */
+    affectsPreference(preferenceName: string): boolean;
+}
+
+/**
+ * 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 ({@link get}, {@link 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. Writes ({@link set}, {@link update})
+ * are never gated by trust.
+ */
+export interface AiConfigurationService {
+    /**
+     * 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.
+     */
+    readonly ready: Promise<void>;
+
+    /**
+     * Retrieves the effective, trust-aware value for the given preference.
+     *
+     * @param key the preference identifier.
+     * @param defaultValue the value to return when no value is stored.
+     * @param resourceUri the uri of the resource for which the preference is read.
+     */
+    get<T>(key: string, defaultValue?: T, resourceUri?: string): T | undefined;
+
+    /**
+     * Writes `value` to the given scope. Maps to `PreferenceService.set`.
+     *
+     * @param key the preference identifier.
+     * @param value the new value (must be JSON-serializable). `undefined` clears the value in the given scope.
+     * @param scope the scope to write to. For {@link PreferenceScope.Folder} a `resourceUri` is required.
+     * @param resourceUri the uri of the resource for which the preference is stored.
+     */
+    set(key: string, value: unknown, scope: PreferenceScope, resourceUri?: string): Promise<void>;
+
+    /**
+     * "Smart write": picks the scope so that the effective value becomes `value`. Maps to
+     * `PreferenceService.updateValue`.
+     *
+     * @param key the preference identifier.
+     * @param value the value to apply (must be JSON-serializable). `undefined` resets the preference to its default value.
+     * @param resourceUri the uri of the resource to which the change applies.
+     */
+    update(key: string, value: unknown, resourceUri?: string): Promise<void>;
+
+    /**
+     * Retrieves the per-scope values for the given preference, enriched with a derived,
+     * trust-aware {@link AiConfigurationInspection.sourceScope} and effective
+     * {@link PreferenceInspection.value}.
+     *
+     * @param key the preference identifier.
+     * @param resourceUri the uri of the resource for which the preference is inspected.
+     */
+    inspect<T extends JSONValue>(key: string, resourceUri?: string): AiConfigurationInspection<T> | undefined;
+
+    /**
+     * 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 {@link get}/{@link inspect}.
+     */
+    onDidChange: Event<AiConfigurationChange>;
+}

package/src/common/ai-core-preferences.ts

@@ -34,11 +34,22 @@ export const PREFERENCE_NAME_REASONING = 'ai-features.reasoning.defaults';
 export const PREFERENCE_NAME_MAX_RETRIES = 'ai-features.modelSettings.maxRetries';
 export const PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE = 'ai-features.notifications.default';
 export const PREFERENCE_NAME_SKILL_DIRECTORIES = 'ai-features.skills.skillDirectories';
+export const PREFERENCE_NAME_SERVER_SIDE_COMPACTION = 'ai-features.chat.serverSideCompaction';
 
 export const LANGUAGE_MODEL_ALIASES_PREFERENCE = 'ai-features.languageModelAliases';
 
 export const aiCorePreferenceSchema: PreferenceSchema = {
     properties: {
+        [PREFERENCE_NAME_SERVER_SIDE_COMPACTION]: {
+            title: AI_CORE_PREFERENCES_TITLE,
+            type: 'boolean',
+            description: nls.localize('theia/ai/core/serverSideCompaction/description',
+                'Enable provider-native server-side compaction by default for chat requests. When on, models that support it ' +
+                'may automatically summarize older turns once the conversation grows past their own threshold, letting long ' +
+                'sessions continue past the context limit. Each provider offers its own override, and individual chat sessions ' +
+                'can override this in their session settings. Models without support ignore it.'),
+            default: true,
+        },
         [PREFERENCE_NAME_PROMPT_TEMPLATES]: {
             title: AI_CORE_PREFERENCES_TITLE,
             description: nls.localize('theia/ai/core/promptTemplates/description',
@@ -239,6 +250,7 @@ export interface AICoreConfiguration {
     [PREFERENCE_NAME_MAX_RETRIES]: number | undefined;
     [PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE]: NotificationType | undefined;
     [PREFERENCE_NAME_SKILL_DIRECTORIES]: string[] | undefined;
+    [PREFERENCE_NAME_SERVER_SIDE_COMPACTION]: boolean | undefined;
 }
 
 export interface RequestSetting {

package/src/common/index.ts

@@ -31,6 +31,7 @@ export * from './protocol';
 export * from './today-variable-contribution';
 export * from './variable-service';
 export * from './settings-service';
+export * from './ai-configuration-service';
 export * from './language-model-service';
 export * from './token-usage-service';
 export * from './ai-variable-resource';

package/src/common/language-model.spec.ts

@@ -15,7 +15,16 @@
 // *****************************************************************************
 
 import { expect } from 'chai';
-import { isModelMatching, isToolCallContent, LanguageModel, LanguageModelSelector } from './language-model';
+import {
+    isCompactionResponsePart,
+    isLanguageModelStreamResponsePart,
+    isModelMatching,
+    isToolCallContent,
+    LanguageModel,
+    LanguageModelSelector,
+    resolveCompactionDefault,
+    resolveServerSideCompaction
+} from './language-model';
 
 describe('isModelMatching', () => {
     it('returns false with one of two parameter mismatches', () => {
@@ -163,3 +172,38 @@ describe('isToolCallContent', () => {
     });
 
 });
+
+describe('compaction contract', () => {
+    it('recognizes a compaction response part', () => {
+        const part = { compaction: { provider: 'anthropic', data: { foo: 1 } } };
+        expect(isCompactionResponsePart(part)).to.equal(true);
+        expect(isLanguageModelStreamResponsePart(part)).to.equal(true);
+    });
+    it('rejects a non-compaction part', () => {
+        expect(isCompactionResponsePart({ content: 'hi' })).to.equal(false);
+        // eslint-disable-next-line no-null/no-null
+        expect(isCompactionResponsePart(null)).to.equal(false);
+        expect(isCompactionResponsePart(undefined)).to.equal(false);
+        // eslint-disable-next-line no-null/no-null
+        expect(isCompactionResponsePart({ compaction: null })).to.equal(false);
+        expect(isCompactionResponsePart({ compaction: { provider: 42 } })).to.equal(false);
+    });
+    it('resolves a model default from the global preference and the per-provider override', () => {
+        expect(resolveCompactionDefault(true, 'default')).to.equal(true);
+        expect(resolveCompactionDefault(false, 'default')).to.equal(false);
+        expect(resolveCompactionDefault(false, 'enabled')).to.equal(true);
+        expect(resolveCompactionDefault(true, 'disabled')).to.equal(false);
+    });
+    it('resolves server-side compaction with capability gate and session-wins precedence', () => {
+        // capability gate
+        expect(resolveServerSideCompaction(false, true, { enabled: true })).to.equal(false);
+        expect(resolveServerSideCompaction(undefined, true, undefined)).to.equal(false);
+        // no per-session setting -> model default
+        expect(resolveServerSideCompaction(true, true, undefined)).to.equal(true);
+        expect(resolveServerSideCompaction(true, false, undefined)).to.equal(false);
+        expect(resolveServerSideCompaction(true, true, {})).to.equal(true);
+        // explicit per-session setting wins over the model default (which already folds in the per-provider override)
+        expect(resolveServerSideCompaction(true, false, { enabled: true })).to.equal(true);
+        expect(resolveServerSideCompaction(true, true, { enabled: false })).to.equal(false);
+    });
+});

package/src/common/language-model.ts

@@ -42,7 +42,8 @@ export interface ReasoningSupport {
     readonly defaultLevel?: ReasoningLevel;
 }
 
-export type LanguageModelMessage = TextMessage | ThinkingMessage | ToolUseMessage | ToolResultMessage | ServerToolUseMessage | ImageMessage;
+export type LanguageModelMessage =
+    TextMessage | ThinkingMessage | ToolUseMessage | ToolResultMessage | ServerToolUseMessage | ImageMessage | CompactionMessage;
 export namespace LanguageModelMessage {
 
     export function isTextMessage(obj: LanguageModelMessage): obj is TextMessage {
@@ -63,6 +64,9 @@ export namespace LanguageModelMessage {
     export function isImageMessage(obj: LanguageModelMessage): obj is ImageMessage {
         return obj.type === 'image';
     }
+    export function isCompactionMessage(obj: LanguageModelMessage): obj is CompactionMessage {
+        return obj.type === 'compaction';
+    }
 }
 export interface TextMessage {
     actor: MessageActor;
@@ -127,6 +131,17 @@ export interface ImageMessage {
     image: ImageContent;
 }
 
+export interface CompactionMessage {
+    actor: 'ai';
+    type: 'compaction';
+    /** Originating provider tag; a backend replays the payload only when this matches its own provider. */
+    provider: string;
+    /** Opaque provider payload to replay. */
+    data: unknown;
+    /** Human-readable summary, when the provider exposes one. */
+    summary?: string;
+}
+
 export const isLanguageModelRequestMessage = (obj: unknown): obj is LanguageModelMessage =>
     !!(obj && typeof obj === 'object' &&
         'type' in obj &&
@@ -304,6 +319,50 @@ export namespace ToolRequest {
             (!('required' in obj) || (Array.isArray(obj.required) && obj.required.every(prop => typeof prop === 'string')));
     }
 }
+/**
+ * Per-session/per-request server-side compaction settings, carried verbatim from the chat
+ * session's common settings to the request. Kept as an object so further parameters can be
+ * added later.
+ */
+export interface CompactionSettings {
+    /** Explicit enablement for this session; when set it wins over the model's default. `undefined` means "no explicit choice". */
+    enabled?: boolean;
+}
+
+/** Per-provider override for server-side compaction; combined with the global preference by {@link resolveCompactionDefault}. */
+export type ServerSideCompactionSetting = 'default' | 'enabled' | 'disabled';
+
+/**
+ * Resolves a model's default server-side compaction enablement from the global preference and
+ * the per-provider override. `'enabled'`/`'disabled'` force the result; `'default'` defers to
+ * the global preference. Intended to be called where the preferences are read (the provider's
+ * frontend contribution) and stored on the model.
+ */
+export function resolveCompactionDefault(globalEnabled: boolean, perProviderOverride: ServerSideCompactionSetting): boolean {
+    if (perProviderOverride === 'enabled') {
+        return true;
+    }
+    if (perProviderOverride === 'disabled') {
+        return false;
+    }
+    return globalEnabled;
+}
+
+/**
+ * Resolves whether server-side compaction is effective for a request: the model must support it
+ * (capability), then an explicit per-session setting wins, otherwise the model's resolved default applies.
+ */
+export function resolveServerSideCompaction(
+    capability: boolean | undefined,
+    enabledByDefault: boolean,
+    compaction: CompactionSettings | undefined
+): boolean {
+    if (!capability) {
+        return false;
+    }
+    return compaction?.enabled ?? enabledByDefault;
+}
+
 export interface LanguageModelRequest {
     messages: LanguageModelMessage[],
     tools?: ToolRequest[];
@@ -323,6 +382,8 @@ export interface LanguageModelRequest {
     clientSettings?: { keepToolCalls: boolean; keepThinking: boolean };
     /** Provider-agnostic reasoning configuration; providers translate it to their native API. */
     reasoning?: ReasoningSettings;
+    /** Provider-agnostic server-side compaction settings, copied verbatim from the chat session. Resolved against the model's capability and default in the backend. */
+    compaction?: CompactionSettings;
 }
 export interface ResponseFormatJsonSchema {
     type: 'json_schema';
@@ -378,10 +439,12 @@ export interface LanguageModelTextResponse {
 export const isLanguageModelTextResponse = (obj: unknown): obj is LanguageModelTextResponse =>
     !!(obj && typeof obj === 'object' && 'text' in obj && typeof (obj as { text: unknown }).text === 'string');
 
-export type LanguageModelStreamResponsePart = TextResponsePart | ToolCallResponsePart | ServerToolCallResponsePart | ThinkingResponsePart | UsageResponsePart;
+export type LanguageModelStreamResponsePart =
+    TextResponsePart | ToolCallResponsePart | ServerToolCallResponsePart | ThinkingResponsePart | UsageResponsePart | CompactionResponsePart;
 
 export const isLanguageModelStreamResponsePart = (part: unknown): part is LanguageModelStreamResponsePart =>
-    isUsageResponsePart(part) || isTextResponsePart(part) || isThinkingResponsePart(part) || isToolCallResponsePart(part) || isServerToolCallResponsePart(part);
+    isUsageResponsePart(part) || isTextResponsePart(part) || isThinkingResponsePart(part) ||
+    isToolCallResponsePart(part) || isServerToolCallResponsePart(part) || isCompactionResponsePart(part);
 
 export interface UsageResponsePart {
     input_tokens: number;
@@ -432,6 +495,23 @@ export interface ThinkingResponsePart {
 export const isThinkingResponsePart = (part: unknown): part is ThinkingResponsePart =>
     !!(part && typeof part === 'object' && 'thought' in part && typeof part.thought === 'string');
 
+export interface CompactionResponsePart {
+    compaction: {
+        /** Originating provider tag, e.g. 'anthropic' or 'openai-responses'. */
+        provider: string;
+        /** Opaque provider payload (Anthropic compaction block(s) / OpenAI compaction item). Never interpreted outside the originating backend. */
+        data: unknown;
+        /** Human-readable summary, when the provider exposes one. */
+        summary?: string;
+    };
+}
+export const isCompactionResponsePart = (part: unknown): part is CompactionResponsePart =>
+    !!(part && typeof part === 'object' && 'compaction' in part &&
+        typeof (part as CompactionResponsePart).compaction === 'object' &&
+        (part as CompactionResponsePart).compaction &&
+        'provider' in (part as CompactionResponsePart).compaction &&
+        typeof (part as CompactionResponsePart).compaction.provider === 'string');
+
 export interface ToolCallTextResult { type: 'text', text: string; };
 export interface ToolCallImageResult extends Base64ImageContent { type: 'image' };
 export interface ToolCallAudioResult { type: 'audio', data: string; mimeType: string };
@@ -530,6 +610,8 @@ export interface LanguageModelMetaData {
      * **Note:** If you provide these, you must also provide `vendor` because server tools are vendor-specific.
      */
     readonly serverTools?: ServerToolDescriptor[];
+    /** Whether this model supports provider-native server-side compaction (capability, distinct from whether it is activated). */
+    readonly serverSideCompactionSupport?: boolean;
 }
 
 export namespace LanguageModelMetaData {

package/src/common/prompt-service.ts

@@ -385,11 +385,21 @@ export interface PromptFragmentCustomizationService {
     createCustomAgentFile(parentDirectory: URI, agent: CustomAgentDescription): Promise<URI>;
 
     /**
-     * Migrates every reachable `customAgents.yml` to the per-agent `agents/<id>/agent.md` layout.
+     * Returns `true` if migration would write anything: a scope still holds a legacy
+     * `customAgents.yml`, or a previously migrated scope has `agent.md` files that can be corrected
+     * (e.g. headings that were folded by an earlier migration). Read-only; performs no writes and is
+     * intended for deciding whether to prompt the user before migrating.
+     */
+    hasPendingCustomAgentMigration(): Promise<boolean>;
+
+    /**
+     * Migrates every reachable `customAgents.yml` to the per-agent `agents/<id>/agent.md` layout and
+     * corrects already-migrated `agent.md` files whose headings were folded by an earlier migration.
      * The user's original content is never deleted: on success (or on partial failure when no backup
      * exists yet) the YAML is renamed to `customAgents.yml.bak`; if a `.bak` already exists it is not
-     * overwritten and the YAML is left in place.
-     * Idempotent — rerunning never overwrites an already-migrated agent file.
+     * overwritten and the YAML is left in place. Corrections only overwrite `agent.md` files the user
+     * has not edited since migration.
+     * Idempotent — rerunning never overwrites an already up-to-date agent file.
      */
     migrateCustomAgentsYaml(): Promise<Array<{
         scope: URI;
@@ -399,6 +409,7 @@ export interface PromptFragmentCustomizationService {
         failed: number;
         yamlBackedUp: boolean;
         promptOverridesMigrated: number;
+        corrected: number;
     }>>;
 
     /**

package/src/node/backend-language-model-registry.ts

@@ -64,6 +64,7 @@ export class BackendLanguageModelRegistryImpl extends DefaultLanguageModelRegist
             maxOutputTokens: model.maxOutputTokens,
             reasoningSupport: model.reasoningSupport,
             serverTools: model.serverTools,
+            serverSideCompactionSupport: model.serverSideCompactionSupport,
         };
     }
 }