@theia/plugin-ext 1.71.0-next.8 → 1.72.0-next.0

package/src/plugin/scm.ts

@@ -28,16 +28,22 @@ import {
     ScmMain, ScmRawResource, ScmRawResourceGroup,
     ScmRawResourceSplice, ScmRawResourceSplices,
     SourceControlGroupFeatures,
-    ScmActionButton
+    ScmActionButton,
+    ScmHistoryItemRefDto,
+    ScmHistoryItemDto,
+    ScmHistoryItemChangeDto,
+    ScmHistoryOptionsDto,
+    ScmHistoryItemRefsChangeEventDto
 } from '../common';
 import { Disposable, DisposableCollection } from '@theia/core/lib/common/disposable';
+import { CancellationToken } from '@theia/core/lib/common/cancellation';
 import { CommandRegistryImpl } from '../plugin/command-registry';
 import { Splice } from '../common/arrays';
 import { UriComponents } from '../common/uri-components';
 import { Command } from '../common/plugin-api-rpc-model';
 import { RPCProtocol } from '../common/rpc-protocol';
 import { URI, ThemeIcon } from './types-impl';
-import { ScmCommandArg } from '../common/plugin-api-rpc';
+import { ScmCommandArg, ScmHistoryItemCommandArg } from '../common/plugin-api-rpc';
 import { sep } from '@theia/core/lib/common/paths';
 import { PluginIconPath } from './plugin-icon-path';
 import { createAPIObject } from './plugin-context';
@@ -538,11 +544,54 @@ class ScmResourceGroupImpl implements theia.SourceControlResourceGroup {
     }
 }
 
+function historyItemRefToDto(ref: theia.SourceControlHistoryItemRef): ScmHistoryItemRefDto {
+    return {
+        id: ref.id,
+        name: ref.name,
+        description: ref.description,
+        revision: ref.revision,
+        icon: ref.icon,
+        category: ref.category,
+    };
+}
+
+function historyItemToDto(item: theia.SourceControlHistoryItem): ScmHistoryItemDto {
+    return {
+        id: item.id,
+        parentIds: item.parentIds ? [...item.parentIds] : undefined,
+        subject: item.subject,
+        message: item.message,
+        author: item.author,
+        authorEmail: item.authorEmail,
+        authorIcon: item.authorIcon,
+        displayId: item.displayId,
+        timestamp: item.timestamp,
+        tooltip: item.tooltip,
+        statistics: item.statistics ? {
+            files: item.statistics.files,
+            insertions: item.statistics.insertions,
+            deletions: item.statistics.deletions,
+        } : undefined,
+        references: item.references ? item.references.map(historyItemRefToDto) : undefined,
+    };
+}
+
+function historyItemChangeToDto(change: theia.SourceControlHistoryItemChange): ScmHistoryItemChangeDto {
+    return {
+        uri: change.uri,
+        originalUri: change.originalUri,
+        modifiedUri: change.modifiedUri,
+        renameUri: change.renameUri,
+    };
+}
+
 class SourceControlImpl implements theia.SourceControl {
 
     private static handlePool: number = 0;
     private groups: Map<GroupHandle, ScmResourceGroupImpl> = new Map<GroupHandle, ScmResourceGroupImpl>();
 
+    readonly apiObject: theia.SourceControl;
+
     get id(): string {
         return this._id;
     }
@@ -687,6 +736,53 @@ class SourceControlImpl implements theia.SourceControl {
         this.proxy.$updateSourceControl(this.handle, { contextValue });
     }
 
+    private _historyProvider: theia.SourceControlHistoryProvider | undefined = undefined;
+    private _historyProviderDisposables = new DisposableCollection();
+
+    readonly historyItems = new Map<string, theia.SourceControlHistoryItem>();
+    readonly historyItemRefs = new Map<string, theia.SourceControlHistoryItemRef>();
+
+    get historyProvider(): theia.SourceControlHistoryProvider | undefined {
+        return this._historyProvider;
+    }
+
+    set historyProvider(provider: theia.SourceControlHistoryProvider | undefined) {
+        this._historyProviderDisposables.dispose();
+        this._historyProviderDisposables = new DisposableCollection();
+        this._historyProvider = provider;
+
+        if (provider) {
+            this._historyProviderDisposables.push(
+                provider.onDidChangeCurrentHistoryItemRefs(() => {
+                    this.proxy.$updateSourceControl(this.handle, {
+                        hasHistoryProvider: true,
+                        currentHistoryItemRef: provider.currentHistoryItemRef ? historyItemRefToDto(provider.currentHistoryItemRef) : undefined,
+                        currentHistoryItemRemoteRef: provider.currentHistoryItemRemoteRef ? historyItemRefToDto(provider.currentHistoryItemRemoteRef) : undefined,
+                        currentHistoryItemBaseRef: provider.currentHistoryItemBaseRef ? historyItemRefToDto(provider.currentHistoryItemBaseRef) : undefined,
+                    });
+                    this.proxy.$onDidChangeCurrentHistoryItemRefs(this.handle);
+                })
+            );
+            this._historyProviderDisposables.push(
+                provider.onDidChangeHistoryItemRefs(event => {
+                    const dto: ScmHistoryItemRefsChangeEventDto = {
+                        added: event.added.map(historyItemRefToDto),
+                        removed: event.removed.map(historyItemRefToDto),
+                        modified: event.modified.map(historyItemRefToDto),
+                    };
+                    this.proxy.$onDidChangeHistoryItemRefs(this.handle, dto);
+                })
+            );
+        }
+
+        this.proxy.$updateSourceControl(this.handle, {
+            hasHistoryProvider: !!provider,
+            currentHistoryItemRef: provider?.currentHistoryItemRef ? historyItemRefToDto(provider.currentHistoryItemRef) : undefined,
+            currentHistoryItemRemoteRef: provider?.currentHistoryItemRemoteRef ? historyItemRefToDto(provider.currentHistoryItemRemoteRef) : undefined,
+            currentHistoryItemBaseRef: provider?.currentHistoryItemBaseRef ? historyItemRefToDto(provider.currentHistoryItemBaseRef) : undefined,
+        });
+    }
+
     private readonly onDidDisposeEmitter = new Emitter<void>();
     readonly onDidDispose = this.onDidDisposeEmitter.event;
 
@@ -702,11 +798,13 @@ class SourceControlImpl implements theia.SourceControl {
         private _label: string,
         private _rootUri?: theia.Uri,
         _iconPath?: theia.IconPath,
+        _isHidden?: boolean,
         _parent?: SourceControlImpl
     ) {
         this.inputBox = new ScmInputBoxImpl(plugin, this.proxy, this.handle);
         this.proxy.$registerSourceControl(this.handle, _id, _label, _rootUri, _parent?.handle);
         this.onDidDisposeParent = _parent ? _parent.onDidDispose : Event.None;
+        this.apiObject = createAPIObject(this);
     }
 
     private createdResourceGroups = new Map<ScmResourceGroupImpl, Disposable>();
@@ -779,6 +877,14 @@ class SourceControlImpl implements theia.SourceControl {
         return this.groups.get(handle);
     }
 
+    getHistoryItem(id: string): theia.SourceControlHistoryItem | undefined {
+        return this.historyItems.get(id);
+    }
+
+    getHistoryItemRef(id: string): theia.SourceControlHistoryItemRef | undefined {
+        return this.historyItemRefs.get(id);
+    }
+
     setSelectionState(selected: boolean): void {
         this._selected = selected;
         this.onDidChangeSelectionEmitter.fire(selected);
@@ -788,6 +894,7 @@ class SourceControlImpl implements theia.SourceControl {
         this.acceptInputDisposables.dispose();
         this._statusBarDisposables.dispose();
         this._actionButtonDisposables.dispose();
+        this._historyProviderDisposables.dispose();
 
         this.groups.forEach(group => group.dispose());
         this.proxy.$unregisterSourceControl(this.handle);
@@ -813,6 +920,32 @@ export class ScmExtImpl implements ScmExt {
     constructor(rpc: RPCProtocol, private commands: CommandRegistryImpl) {
         this.proxy = rpc.getProxy(PLUGIN_RPC_CONTEXT.SCM_MAIN);
 
+        // Register history item arg processor before the generic ScmCommandArg processor
+        // so the more-specific guard matches first.
+        commands.registerArgumentProcessor({
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            processArgument: (arg: any) => {
+                if (!ScmHistoryItemCommandArg.is(arg) || arg.type !== 'historyItem') {
+                    return arg;
+                }
+                const sourceControl = this.sourceControls.get(arg.sourceControlHandle);
+                const item = sourceControl?.getHistoryItem(arg.id);
+                return item ?? { id: arg.id };
+            }
+        });
+
+        commands.registerArgumentProcessor({
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            processArgument: (arg: any) => {
+                if (!ScmHistoryItemCommandArg.is(arg) || arg.type !== 'historyItemRef') {
+                    return arg;
+                }
+                const sourceControl = this.sourceControls.get(arg.sourceControlHandle);
+                const ref = sourceControl?.getHistoryItemRef(arg.id);
+                return ref ?? { id: arg.id };
+            }
+        });
+
         commands.registerArgumentProcessor({
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             processArgument: (arg: any) => {
@@ -824,7 +957,7 @@ export class ScmExtImpl implements ScmExt {
                     return undefined;
                 }
                 if (typeof arg.resourceGroupHandle !== 'number') {
-                    return sourceControl;
+                    return sourceControl.apiObject;
                 }
                 const resourceGroup = sourceControl.getResourceGroup(arg.resourceGroupHandle);
                 if (typeof arg.resourceStateHandle !== 'number') {
@@ -836,17 +969,35 @@ export class ScmExtImpl implements ScmExt {
     }
 
     createSourceControl(extension: Plugin, id: string, label: string, rootUri: theia.Uri | undefined,
-        iconPath?: theia.IconPath, parent?: theia.SourceControl): theia.SourceControl {
+        iconPath?: theia.IconPath, isHidden?: boolean, parent?: theia.SourceControl): theia.SourceControl {
         const handle = ScmExtImpl.handlePool++;
         const parentImpl = parent ? this.findSourceControlImpl(parent) : undefined;
-        const sourceControl = new SourceControlImpl(extension, this.proxy, this.commands, id, label, rootUri, iconPath, parentImpl);
+        const sourceControl = new SourceControlImpl(extension, this.proxy, this.commands, id, label, rootUri, iconPath, isHidden, parentImpl);
         this.sourceControls.set(handle, sourceControl);
 
         const sourceControls = this.sourceControlsByExtension.get(extension.model.id) || [];
         sourceControls.push(sourceControl);
         this.sourceControlsByExtension.set(extension.model.id, sourceControls);
 
-        return sourceControl;
+        // Clean up registries when the source control is disposed. Without this,
+        // disposed entries leak and findSourceControlImpl() may return a stale
+        // (disposed) instance as a parent for a later-created source control
+        // with the same id + rootUri (e.g. a worktree recreated after removal).
+        sourceControl.onDidDispose(() => {
+            this.sourceControls.delete(handle);
+            const list = this.sourceControlsByExtension.get(extension.model.id);
+            if (list) {
+                const index = list.indexOf(sourceControl);
+                if (index >= 0) {
+                    list.splice(index, 1);
+                }
+                if (list.length === 0) {
+                    this.sourceControlsByExtension.delete(extension.model.id);
+                }
+            }
+        });
+
+        return sourceControl.apiObject;
     }
 
     private findSourceControlImpl(apiObject: theia.SourceControl): SourceControlImpl | undefined {
@@ -920,6 +1071,73 @@ export class ScmExtImpl implements ScmExt {
         return [result.message, result.type];
     }
 
+    async $provideHistoryItemRefs(sourceControlHandle: number, historyItemRefs: string[] | undefined, token: CancellationToken): Promise<ScmHistoryItemRefDto[] | undefined> {
+        const sourceControl = this.sourceControls.get(sourceControlHandle);
+        if (!sourceControl || !sourceControl.historyProvider) {
+            return undefined;
+        }
+        const result = await sourceControl.historyProvider.provideHistoryItemRefs(historyItemRefs, token);
+        if (!result) {
+            return undefined;
+        }
+        sourceControl.historyItemRefs.clear();
+        for (const ref of result) {
+            sourceControl.historyItemRefs.set(ref.id, ref);
+        }
+        return result.map(historyItemRefToDto);
+    }
+
+    async $provideHistoryItems(sourceControlHandle: number, options: ScmHistoryOptionsDto, token: CancellationToken): Promise<ScmHistoryItemDto[] | undefined> {
+        const sourceControl = this.sourceControls.get(sourceControlHandle);
+        if (!sourceControl || !sourceControl.historyProvider) {
+            return undefined;
+        }
+        const result = await sourceControl.historyProvider.provideHistoryItems(options, token);
+        if (!result) {
+            return undefined;
+        }
+        for (const item of result) {
+            sourceControl.historyItems.set(item.id, item);
+        }
+        return result.map(historyItemToDto);
+    }
+
+    async $provideHistoryItemChanges(
+        sourceControlHandle: number, historyItemId: string,
+        historyItemParentId: string | undefined, token: CancellationToken
+    ): Promise<ScmHistoryItemChangeDto[] | undefined> {
+        const sourceControl = this.sourceControls.get(sourceControlHandle);
+        if (!sourceControl || !sourceControl.historyProvider) {
+            return undefined;
+        }
+        const result = await sourceControl.historyProvider.provideHistoryItemChanges(historyItemId, historyItemParentId, token);
+        if (!result) {
+            return undefined;
+        }
+        return result.map(historyItemChangeToDto);
+    }
+
+    async $resolveHistoryItem(sourceControlHandle: number, historyItemId: string, token: CancellationToken): Promise<ScmHistoryItemDto | undefined> {
+        const sourceControl = this.sourceControls.get(sourceControlHandle);
+        if (!sourceControl || !sourceControl.historyProvider) {
+            return undefined;
+        }
+        const result = await sourceControl.historyProvider.resolveHistoryItem(historyItemId, token);
+        if (!result) {
+            return undefined;
+        }
+        return historyItemToDto(result);
+    }
+
+    async $resolveHistoryItemRefsCommonAncestor(sourceControlHandle: number, historyItemRefs: string[], token: CancellationToken): Promise<string | undefined> {
+        const sourceControl = this.sourceControls.get(sourceControlHandle);
+        if (!sourceControl || !sourceControl.historyProvider) {
+            return undefined;
+        }
+        const result = await sourceControl.historyProvider.resolveHistoryItemRefsCommonAncestor(historyItemRefs, token);
+        return result ?? undefined;
+    }
+
     $setSelectedSourceControl(selectedSourceControlHandle: number | undefined): Promise<void> {
         if (selectedSourceControlHandle !== undefined) {
             this.sourceControls.get(selectedSourceControlHandle)?.setSelectionState(true);

package/src/plugin/terminal-ext.spec.ts

@@ -0,0 +1,350 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource and others.
+//
+// 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 * as chai from 'chai';
+import * as theia from '@theia/plugin';
+import { TerminalServiceMain, Plugin, TerminalOptions } from '../common/plugin-api-rpc';
+import { RPCProtocol, ProxyIdentifier } from '../common/rpc-protocol';
+import { TerminalServiceExtImpl, TerminalExtImpl } from './terminal-ext';
+import { TerminalExitReason } from './types-impl';
+
+const expect = chai.expect;
+
+/**
+ * Creates a mock RPCProtocol that returns the given proxy for TERMINAL_MAIN.
+ */
+function createMockRpc(proxy: Partial<TerminalServiceMain>): RPCProtocol {
+    return {
+        getProxy<T>(_proxyId: ProxyIdentifier<T>): T {
+            return proxy as unknown as T;
+        },
+        set<T, R extends T>(_identifier: ProxyIdentifier<T>, instance: R): R {
+            return instance;
+        },
+        dispose(): void { }
+    } as RPCProtocol;
+}
+
+/**
+ * Creates a minimal mock Plugin object.
+ */
+function createMockPlugin(): Plugin {
+    return {
+        pluginPath: '/test',
+        pluginFolder: '/test',
+        pluginUri: 'file:///test',
+        model: { id: 'test.plugin' } as Plugin['model'],
+        rawModel: {} as Plugin['rawModel'],
+        lifecycle: {} as Plugin['lifecycle'],
+        isUnderDevelopment: false
+    };
+}
+
+/**
+ * Creates a stub TerminalServiceMain that records calls.
+ */
+function createMockProxy(): TerminalServiceMain & { createdTerminals: { id: string; options: TerminalOptions }[] } {
+    const createdTerminals: { id: string; options: TerminalOptions }[] = [];
+    return {
+        createdTerminals,
+        $createTerminal(id: string, options: TerminalOptions): Promise<string> {
+            createdTerminals.push({ id, options });
+            return Promise.resolve(id);
+        },
+        $sendText(): void { },
+        $write(): void { },
+        $resize(): void { },
+        $show(): void { },
+        $hide(): void { },
+        $dispose(): void { },
+        $setName(): void { },
+        $writeByTerminalId(): void { },
+        $resizeByTerminalId(): void { },
+        $disposeByTerminalId(): void { },
+        $setNameByTerminalId(): void { },
+        $setEnvironmentVariableCollection(): void { },
+        $registerTerminalLinkProvider(): void { },
+        $unregisterTerminalLinkProvider(): void { },
+        $registerTerminalObserver(): void { },
+        $unregisterTerminalObserver(): void { },
+    } as unknown as TerminalServiceMain & { createdTerminals: { id: string; options: TerminalOptions }[] };
+}
+
+describe('TerminalServiceExtImpl', () => {
+    let proxy: ReturnType<typeof createMockProxy>;
+    let service: TerminalServiceExtImpl;
+    let plugin: Plugin;
+
+    beforeEach(() => {
+        proxy = createMockProxy();
+        const rpc = createMockRpc(proxy);
+        service = new TerminalServiceExtImpl(rpc);
+        plugin = createMockPlugin();
+    });
+
+    describe('terminals list', () => {
+        it('returns empty array initially', () => {
+            expect(service.terminals).to.deep.equal([]);
+        });
+
+        it('includes terminals after creation via $terminalCreated', () => {
+            service.$terminalCreated('t1', 'Terminal 1');
+            expect(service.terminals).to.have.length(1);
+        });
+
+        it('removes terminals after $terminalClosed', () => {
+            service.$terminalCreated('t1', 'Terminal 1');
+            service.$terminalClosed('t1', { code: 0, reason: TerminalExitReason.Process });
+            expect(service.terminals).to.have.length(0);
+        });
+    });
+
+    describe('API object identity', () => {
+        it('returns the raw TerminalExtImpl when no wrapper is provided', () => {
+            const terminal = service.createTerminal(plugin, 'Test Terminal');
+            expect(terminal).to.be.instanceOf(TerminalExtImpl);
+        });
+
+        it('returns the wrapped API object when a wrapper is provided', () => {
+            const wrapper = (t: TerminalExtImpl): theia.Terminal => ({ ...t, name: 'wrapped' } as unknown as theia.Terminal);
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+            const terminal = service.terminals[0];
+            expect(terminal.name).to.equal('wrapped');
+            expect(terminal).to.not.be.instanceOf(TerminalExtImpl);
+        });
+
+        it('fires onDidOpenTerminal with the API object, not the raw terminal', () => {
+            const apiObject = { marker: 'api-object' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+
+            const opened: theia.Terminal[] = [];
+            service.onDidOpenTerminal(t => opened.push(t));
+
+            // Get the ID from the proxy call
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+
+            expect(opened).to.have.length(1);
+            expect(opened[0]).to.equal(apiObject);
+        });
+
+        it('fires onDidCloseTerminal with the API object', () => {
+            const apiObject = { marker: 'api-object' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+
+            const closed: theia.Terminal[] = [];
+            service.onDidCloseTerminal(t => closed.push(t));
+
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+            service.$terminalClosed(id, { code: 0, reason: TerminalExitReason.Process });
+
+            expect(closed).to.have.length(1);
+            expect(closed[0]).to.equal(apiObject);
+        });
+
+        it('fires onDidChangeTerminalState with the API object on interaction', () => {
+            const apiObject = { marker: 'api-object' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+
+            const stateChanged: theia.Terminal[] = [];
+            service.onDidChangeTerminalState(t => stateChanged.push(t));
+
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+            service.$terminalOnInteraction(id);
+
+            expect(stateChanged).to.have.length(1);
+            expect(stateChanged[0]).to.equal(apiObject);
+        });
+
+        it('fires onDidChangeTerminalState with the API object on shell type change', () => {
+            const apiObject = { marker: 'api-object' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+
+            const stateChanged: theia.Terminal[] = [];
+            service.onDidChangeTerminalState(t => stateChanged.push(t));
+
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+            service.$terminalShellTypeChanged(id, '/bin/zsh');
+
+            expect(stateChanged).to.have.length(1);
+            expect(stateChanged[0]).to.equal(apiObject);
+        });
+
+        it('returns the API object from the terminals list', () => {
+            const apiObject = { marker: 'api-object' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+
+            const terminals = service.terminals;
+            expect(terminals).to.have.length(1);
+            expect(terminals[0]).to.equal(apiObject);
+        });
+
+        it('returns the API object as activeTerminal', () => {
+            const apiObject = { marker: 'api-object' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+            service.$currentTerminalChanged(id);
+
+            expect(service.activeTerminal).to.equal(apiObject);
+        });
+
+        it('cleans up API object on terminal close', () => {
+            const apiObject = { marker: 'api-object' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Test Terminal', undefined, undefined, wrapper);
+
+            const id = proxy.createdTerminals[0].id;
+            service.$terminalCreated(id, 'Test Terminal');
+            service.$terminalClosed(id, { code: 0, reason: TerminalExitReason.Process });
+
+            expect(service.terminals).to.have.length(0);
+        });
+    });
+
+    describe('parentTerminal resolution', () => {
+        it('resolves parentTerminal from API proxy objects', () => {
+            const apiObject = { marker: 'parent-api' } as unknown as theia.Terminal;
+            const wrapper = (_t: TerminalExtImpl): theia.Terminal => apiObject;
+            service.createTerminal(plugin, 'Parent', undefined, undefined, wrapper);
+
+            const parentId = proxy.createdTerminals[0].id;
+            service.$terminalCreated(parentId, 'Parent');
+
+            // Create a child with parentTerminal set to the API object
+            service.createTerminal(plugin, {
+                name: 'Child',
+                location: { parentTerminal: apiObject }
+            } as theia.TerminalOptions);
+
+            expect(proxy.createdTerminals).to.have.length(2);
+            // The second createTerminal call should have passed the parent ID
+            // We verify it was called on the proxy (the parentId arg is the 3rd parameter)
+        });
+
+        it('resolves parentTerminal from raw terminal objects', () => {
+            const rawTerminal = service.createTerminal(plugin, 'Parent');
+
+            const parentId = proxy.createdTerminals[0].id;
+            service.$terminalCreated(parentId, 'Parent');
+
+            // Create a child with parentTerminal set to the raw terminal
+            service.createTerminal(plugin, {
+                name: 'Child',
+                location: { parentTerminal: rawTerminal }
+            } as theia.TerminalOptions);
+
+            expect(proxy.createdTerminals).to.have.length(2);
+        });
+    });
+
+    describe('events for terminals without wrapper', () => {
+        it('fires onDidOpenTerminal with the raw terminal when no wrapper is used', () => {
+            const opened: theia.Terminal[] = [];
+            service.onDidOpenTerminal(t => opened.push(t));
+
+            service.$terminalCreated('ext-t1', 'External Terminal');
+
+            expect(opened).to.have.length(1);
+            expect(opened[0]).to.be.instanceOf(TerminalExtImpl);
+            expect(opened[0].name).to.equal('External Terminal');
+        });
+
+        it('fires onDidCloseTerminal with the raw terminal when no wrapper is used', () => {
+            const closed: theia.Terminal[] = [];
+            service.onDidCloseTerminal(t => closed.push(t));
+
+            service.$terminalCreated('ext-t1', 'External Terminal');
+            service.$terminalClosed('ext-t1', { code: 0, reason: TerminalExitReason.Process });
+
+            expect(closed).to.have.length(1);
+            expect(closed[0]).to.be.instanceOf(TerminalExtImpl);
+        });
+    });
+
+    describe('shell change', () => {
+        it('fires onDidChangeShell when shell changes', async () => {
+            const shells: string[] = [];
+            service.onDidChangeShell(s => shells.push(s));
+
+            await service.$setShell('/bin/zsh');
+
+            expect(shells).to.deep.equal(['/bin/zsh']);
+            expect(service.defaultShell).to.equal('/bin/zsh');
+        });
+
+        it('does not fire onDidChangeShell when shell is the same', async () => {
+            const shells: string[] = [];
+            await service.$setShell('/bin/zsh');
+
+            service.onDidChangeShell(s => shells.push(s));
+            await service.$setShell('/bin/zsh');
+
+            expect(shells).to.deep.equal([]);
+        });
+    });
+
+    describe('$terminalNameChanged', () => {
+        it('updates the terminal name', () => {
+            service.$terminalCreated('t1', 'Old Name');
+            service.$terminalNameChanged('t1', 'New Name');
+
+            expect(service.terminals[0].name).to.equal('New Name');
+        });
+    });
+
+    describe('activeTerminal', () => {
+        it('is undefined initially', () => {
+            expect(service.activeTerminal).to.equal(undefined);
+        });
+
+        it('reflects the current active terminal', () => {
+            service.$terminalCreated('t1', 'Terminal 1');
+            service.$currentTerminalChanged('t1');
+
+            expect(service.activeTerminal).to.not.equal(undefined);
+            expect(service.activeTerminal!.name).to.equal('Terminal 1');
+        });
+
+        it('fires onDidChangeActiveTerminal', () => {
+            const changes: (theia.Terminal | undefined)[] = [];
+            service.onDidChangeActiveTerminal(t => changes.push(t));
+
+            service.$terminalCreated('t1', 'Terminal 1');
+            service.$currentTerminalChanged('t1');
+            service.$currentTerminalChanged(undefined);
+
+            expect(changes).to.have.length(2);
+            expect(changes[0]!.name).to.equal('Terminal 1');
+            expect(changes[1]).to.equal(undefined);
+        });
+    });
+});