@theia/ai-external-api 1.76.0-next.33

package/src/node/ai-external-api-backend-module.ts

@@ -0,0 +1,41 @@
+// *****************************************************************************
+// 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 { ConnectionHandler, RpcConnectionHandler } from '@theia/core';
+import { ContainerModule } from '@theia/core/shared/inversify';
+import { ExternalApiContribution } from '@theia/external-api/lib/node/external-api-contribution';
+import { EXTERNAL_CHAT_SESSION_PROVIDER_PATH, ExternalChatSessionBackendService, ExternalChatSessionProvider } from '../common/external-chat-session-provider';
+import { AIExternalApiEndpoint } from './ai-external-api-endpoint';
+import { ExternalChatSessionRegistry } from './external-chat-session-registry';
+
+export default new ContainerModule(bind => {
+    bind(ExternalChatSessionRegistry).toSelf().inSingletonScope();
+
+    bind(AIExternalApiEndpoint).toSelf().inSingletonScope();
+    bind(ExternalApiContribution).toService(AIExternalApiEndpoint);
+
+    bind(ConnectionHandler).toDynamicValue(ctx =>
+        new RpcConnectionHandler<ExternalChatSessionProvider>(EXTERNAL_CHAT_SESSION_PROVIDER_PATH, provider => {
+            const registry = ctx.container.get(ExternalChatSessionRegistry);
+            registry.addProvider(provider);
+            provider.onDidCloseConnection(() => registry.removeProvider(provider));
+            const backendService: ExternalChatSessionBackendService = {
+                notifySessionsChanged: () => registry.notifySessionsChanged()
+            };
+            return backendService;
+        })
+    ).inSingletonScope();
+});

package/src/node/ai-external-api-endpoint.spec.ts

@@ -0,0 +1,272 @@
+// *****************************************************************************
+// 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 { Emitter } from '@theia/core';
+import * as express from '@theia/core/shared/express';
+import { ExternalApiRouter } from '@theia/external-api/lib/node/external-api-router';
+import { ExternalApiTestSupport } from '@theia/external-api/lib/node/test/external-api-test-support';
+import { expect } from 'chai';
+import * as http from 'http';
+import { AddressInfo } from 'net';
+import { ExternalChatSessionSummary } from '../common/external-chat-session-provider';
+import { AIExternalApiEndpoint } from './ai-external-api-endpoint';
+import { ExternalChatSessionRegistry } from './external-chat-session-registry';
+
+describe('AIExternalApiEndpoint', () => {
+
+    const sessions: ExternalChatSessionSummary[] = [
+        {
+            id: '1', title: 'session', status: 'running', lastInteraction: 100, workspace: 'file:///test/workspace',
+            preview: 'fix the build\nSure.', agentId: 'coder', agentName: 'Coder', restored: true
+        }
+    ];
+
+    let server: http.Server | undefined;
+
+    afterEach(() => {
+        server?.close();
+        server?.closeAllConnections();
+        server = undefined;
+    });
+
+    interface ServedEndpoint {
+        url: string;
+        router: ExternalApiRouter;
+        sessionsChanged: Emitter<void>;
+    }
+
+    async function serve(registry: Partial<ExternalChatSessionRegistry> = {}): Promise<ServedEndpoint> {
+        const sessionsChanged = new Emitter<void>();
+        const endpoint = ExternalApiTestSupport.inject(new AIExternalApiEndpoint(), {
+            registry: {
+                getSessions: async () => sessions,
+                getSession: async (id: string) => sessions.find(candidate => candidate.id === id),
+                openSession: async (id: string) => sessions.some(candidate => candidate.id === id),
+                restoreSession: async (id: string) => sessions.find(candidate => candidate.id === id),
+                sendPrompt: async (id: string) => sessions.some(candidate => candidate.id === id)
+                    ? { sent: { sessionId: id, requestId: 'r1' } }
+                    : undefined,
+                createSession: async () => ({ created: { session: sessions[0], requestId: 'r1' } }),
+                onDidChangeSessions: sessionsChanged.event,
+                ...registry
+            }
+        });
+        const app = express();
+        const router = ExternalApiTestSupport.mountContribution(app, endpoint);
+        const listening = new Promise<void>(resolve => {
+            server = app.listen(0, '127.0.0.1', () => resolve());
+        });
+        await listening;
+        return { url: `http://127.0.0.1:${(server!.address() as AddressInfo).port}${endpoint.path}`, router, sessionsChanged };
+    }
+
+    function eventData(event: string | undefined): unknown {
+        const data = event?.split('\n').find(line => line.startsWith('data: '));
+        expect(data, `expected a data line in event: ${event}`).to.not.equal(undefined);
+        return JSON.parse(data!.substring('data: '.length));
+    }
+
+    it('lists sessions', async () => {
+        const { url } = await serve();
+        const response = await fetch(url);
+        expect(response.status).to.equal(200);
+        expect(await response.json()).to.deep.equal({ sessions });
+    });
+
+    it('returns a single session', async () => {
+        const { url } = await serve();
+        const response = await fetch(`${url}/1`);
+        expect(response.status).to.equal(200);
+        expect(await response.json()).to.deep.equal(sessions[0]);
+    });
+
+    it('returns 404 for unknown sessions', async () => {
+        const { url } = await serve();
+        const response = await fetch(`${url}/missing`);
+        expect(response.status).to.equal(404);
+        expect(await response.json()).to.deep.equal({ error: 'not found' });
+    });
+
+    it('returns 500 when gathering session data fails', async () => {
+        const { url } = await serve({ getSessions: async () => { throw new Error('boom'); } });
+        const response = await fetch(url);
+        expect(response.status).to.equal(500);
+        expect(await response.json()).to.deep.equal({ error: 'internal error' });
+    });
+
+    describe('open and restore', () => {
+        it('opens a session', async () => {
+            const opened: string[] = [];
+            const { url } = await serve({ openSession: async (id: string) => { opened.push(id); return true; } });
+            const response = await fetch(`${url}/1/open`, { method: 'POST' });
+            expect(response.status).to.equal(204);
+            expect(opened).to.deep.equal(['1']);
+        });
+
+        it('returns 404 when opening an unknown session', async () => {
+            const { url } = await serve();
+            const response = await fetch(`${url}/missing/open`, { method: 'POST' });
+            expect(response.status).to.equal(404);
+        });
+
+        it('restores a session and returns its detail', async () => {
+            const { url } = await serve();
+            const response = await fetch(`${url}/1/restore`, { method: 'POST' });
+            expect(response.status).to.equal(200);
+            expect(await response.json()).to.deep.equal(sessions[0]);
+        });
+
+        it('returns 404 when restoring an unknown session', async () => {
+            const { url } = await serve();
+            const response = await fetch(`${url}/missing/restore`, { method: 'POST' });
+            expect(response.status).to.equal(404);
+        });
+    });
+
+    describe('create and prompt', () => {
+        function post(url: string, body: unknown): Promise<Response> {
+            return fetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: typeof body === 'string' ? body : JSON.stringify(body)
+            });
+        }
+
+        it('creates a session', async () => {
+            const { url } = await serve();
+            const response = await post(url, { workspace: 'file:///test/workspace', agentId: 'coder', prompt: 'fix the build' });
+            expect(response.status).to.equal(201);
+            expect(await response.json()).to.deep.equal({ session: sessions[0], requestId: 'r1' });
+        });
+
+        it('rejects an invalid creation request with the validation errors as details', async () => {
+            const { url } = await serve();
+            const response = await post(url, { focus: 'yes' });
+            expect(response.status).to.equal(400);
+            const body = await response.json();
+            expect(body.error).to.equal('invalid request');
+            expect(body.details).to.have.length(1);
+            expect(body.details[0]).to.contain('focus');
+        });
+
+        it('rejects a creation request with a blank workspace', async () => {
+            const { url } = await serve();
+            const response = await post(url, { workspace: '   ' });
+            expect(response.status).to.equal(400);
+            const error = await response.json();
+            expect(error.error).to.equal('invalid request');
+            expect(error.details[0]).to.contain('workspace');
+        });
+
+        it('rejects an unknown agent', async () => {
+            const { url } = await serve({ createSession: async () => ({ failure: 'unknownAgent' }) });
+            const response = await post(url, { agentId: 'ghost' });
+            expect(response.status).to.equal(400);
+            expect(await response.json()).to.deep.equal({ error: 'unknown agent' });
+        });
+
+        it('rejects an unknown workspace', async () => {
+            const { url } = await serve({ createSession: async () => ({ failure: 'workspaceNotFound' }) });
+            const response = await post(url, { workspace: 'file:///other' });
+            expect(response.status).to.equal(404);
+            expect(await response.json()).to.deep.equal({ error: 'workspace not found' });
+        });
+
+        it('rejects a creation request when no frontend is connected', async () => {
+            const { url } = await serve({ createSession: async () => ({ failure: 'noFrontend' }) });
+            const response = await post(url, {});
+            expect(response.status).to.equal(503);
+            expect(await response.json()).to.deep.equal({ error: 'no frontend connected' });
+        });
+
+        it('rejects an ambiguous workspace', async () => {
+            const { url } = await serve({ createSession: async () => ({ failure: 'ambiguousWorkspace' }) });
+            const response = await post(url, {});
+            expect(response.status).to.equal(409);
+            expect(await response.json()).to.deep.equal({ error: 'ambiguous workspace' });
+        });
+
+        it('sends a prompt to a session', async () => {
+            const { url } = await serve();
+            const response = await post(`${url}/1/prompt`, { text: 'continue' });
+            expect(response.status).to.equal(202);
+            expect(await response.json()).to.deep.equal({ sessionId: '1', requestId: 'r1' });
+        });
+
+        it('returns 404 when prompting an unknown session', async () => {
+            const { url } = await serve();
+            const response = await post(`${url}/missing/prompt`, { text: 'continue' });
+            expect(response.status).to.equal(404);
+        });
+
+        it('returns 409 when the session is busy', async () => {
+            const { url } = await serve({ sendPrompt: async () => ({ failure: 'busy' }) });
+            const response = await post(`${url}/1/prompt`, { text: 'continue' });
+            expect(response.status).to.equal(409);
+            expect(await response.json()).to.deep.equal({ error: 'busy' });
+        });
+
+        it('returns 409 when no agent is available', async () => {
+            const { url } = await serve({ sendPrompt: async () => ({ failure: 'noAgent' }) });
+            const response = await post(`${url}/1/prompt`, { text: 'continue' });
+            expect(response.status).to.equal(409);
+            expect(await response.json()).to.deep.equal({ error: 'no agent available' });
+        });
+
+        it('rejects a prompt without text', async () => {
+            const { url } = await serve();
+            const response = await post(`${url}/1/prompt`, { text: '   ' });
+            expect(response.status).to.equal(400);
+            const error = await response.json();
+            expect(error.error).to.equal('invalid request');
+            expect(error.details[0]).to.contain('text');
+        });
+    });
+
+    describe('events', () => {
+        it('streams the current sessions on connect', async () => {
+            const { url } = await serve();
+            const response = await fetch(`${url}/events`);
+            expect(response.status).to.equal(200);
+            expect(response.headers.get('content-type')).to.equal('text/event-stream');
+            const events = ExternalApiTestSupport.sseReader(response);
+            const first = await events.next();
+            expect(first).to.contain('event: sessions');
+            expect(eventData(first)).to.deep.equal({ sessions });
+            await events.cancel();
+        });
+
+        it('pushes an updated list when sessions change', async () => {
+            const { url, sessionsChanged } = await serve();
+            const response = await fetch(`${url}/events`);
+            const events = ExternalApiTestSupport.sseReader(response);
+            await events.next();
+            sessionsChanged.fire();
+            const update = await events.next();
+            expect(eventData(update)).to.deep.equal({ sessions });
+            await events.cancel();
+        });
+
+        it('closes event streams when the routing is rebuilt', async () => {
+            const { url, router } = await serve();
+            const response = await fetch(`${url}/events`);
+            const events = ExternalApiTestSupport.sseReader(response);
+            await events.next();
+            router.dispose();
+            expect(await events.next()).to.equal(undefined);
+        });
+    });
+});

package/src/node/ai-external-api-endpoint.ts

@@ -0,0 +1,195 @@
+// *****************************************************************************
+// 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 { IJSONSchema } from '@theia/core/lib/common/json-schema';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { ExternalApiContribution, ExternalApiContributionDocumentation } from '@theia/external-api/lib/node/external-api-contribution';
+import { ExternalApiRouter, RestParamDocumentation } from '@theia/external-api/lib/node/external-api-router';
+import { RestResult } from '@theia/external-api/lib/node/rest-result';
+import {
+    AI_SESSIONS_API_PATH, ExternalChatPrompt, ExternalChatSessionCreateRequest, ExternalChatSessionDetail, ExternalChatSessionSummary
+} from '../common/external-chat-session-provider';
+import { ExternalChatSessionRegistry } from './external-chat-session-registry';
+
+const SESSION_ID_PARAM: RestParamDocumentation = { description: 'The session id.' };
+
+const SESSION_LIST_SCHEMA: IJSONSchema = {
+    type: 'object',
+    required: ['sessions'],
+    properties: {
+        sessions: { type: 'array', items: ExternalChatSessionSummary.SCHEMA, description: 'The sessions, most recently used first.' }
+    }
+};
+
+const SESSION_CREATED_SCHEMA: IJSONSchema = {
+    type: 'object',
+    required: ['session'],
+    properties: {
+        session: ExternalChatSessionSummary.SCHEMA,
+        requestId: { type: 'string', description: 'Id of the request created for the initial prompt; absent when no prompt was sent.' }
+    }
+};
+
+const PROMPT_ACCEPTED_SCHEMA: IJSONSchema = {
+    type: 'object',
+    required: ['sessionId', 'requestId'],
+    properties: {
+        sessionId: { type: 'string', description: 'Id of the prompted session.' },
+        requestId: { type: 'string', description: 'Id of the created request.' }
+    }
+};
+
+/**
+ * Contributes the AI session API to the external API server:
+ * - `GET /api/ai/sessions` lists all sessions (restored and persisted) with id, title, status,
+ *   agent, workspace, last interaction time, and a short plain-text preview of the conversation.
+ * - `POST /api/ai/sessions` creates a session in a frontend matching the requested workspace,
+ *   optionally pinning an agent and sending an initial prompt.
+ * - `GET /api/ai/sessions/events` streams the session list as server-sent events, pushing an
+ *   updated list whenever sessions change.
+ * - `GET /api/ai/sessions/:id` returns a single session including its conversation reduced to
+ *   plain-text messages (persisted sessions report metadata only until restored).
+ * - `POST /api/ai/sessions/:id/open` shows the session in the chat view of a connected frontend.
+ * - `POST /api/ai/sessions/:id/restore` restores a persisted session and returns its detail.
+ * - `POST /api/ai/sessions/:id/prompt` sends a prompt to the session.
+ *
+ * The endpoints are served on the external API port and are token-protected when an
+ * external API token is configured (see `@theia/external-api`).
+ */
+@injectable()
+export class AIExternalApiEndpoint implements ExternalApiContribution {
+
+    readonly path = AI_SESSIONS_API_PATH;
+
+    readonly documentation: ExternalApiContributionDocumentation = {
+        title: 'AI Chat Sessions',
+        description: 'Inspect, follow, open, prompt, and create the AI chat sessions of this Theia instance.'
+    };
+
+    @inject(ExternalChatSessionRegistry)
+    protected readonly registry: ExternalChatSessionRegistry;
+
+    configure(router: ExternalApiRouter): void {
+        router.get('/', {
+            operationId: 'listChatSessions',
+            summary: 'List all AI chat sessions, most recently used first.',
+            responses: {
+                200: { description: 'The current sessions of all connected frontends.', schema: SESSION_LIST_SCHEMA }
+            }
+        }, async () => RestResult.ok({ sessions: await this.registry.getSessions() }));
+        // register before '/:id' so that 'events' is not treated as a session id
+        const events = router.eventStream('/events', {
+            event: 'sessions',
+            operationId: 'streamChatSessions',
+            summary: 'Stream the session list as server-sent events.',
+            description: 'On connect, the stream immediately delivers the current session list; afterwards, the full, '
+                + 'updated list is pushed whenever sessions change. Consume each event as a replacement, not a delta.',
+            dataSchema: SESSION_LIST_SCHEMA,
+            snapshot: async () => ({ sessions: await this.registry.getSessions() })
+        });
+        router.toDispose.push(this.registry.onDidChangeSessions(() => events.notifyChanged()));
+        router.get('/:id', {
+            operationId: 'getChatSession',
+            summary: 'Get a single session including its conversation reduced to plain-text messages.',
+            params: { id: SESSION_ID_PARAM },
+            responses: {
+                200: {
+                    description: 'The session detail. Persisted sessions that are not restored carry no messages.',
+                    schema: ExternalChatSessionDetail.SCHEMA
+                },
+                404: { description: 'The session is unknown to all connected frontends.' }
+            }
+        }, async ({ params }) => {
+            const session = await this.registry.getSession(params.id);
+            return session ? RestResult.ok(session) : RestResult.notFound();
+        });
+        router.post('/', {
+            operationId: 'createChatSession',
+            summary: 'Create a chat session in a connected frontend and optionally send an initial prompt.',
+            bodySchema: ExternalChatSessionCreateRequest.SCHEMA,
+            responses: {
+                201: { description: 'The created session and, if an initial prompt was sent, the id of the created request.', schema: SESSION_CREATED_SCHEMA },
+                400: { description: 'The requested agent is not registered.' },
+                404: { description: 'No connected frontend matches the requested workspace.' },
+                409: { description: 'The workspace is ambiguous or no agent could handle the initial prompt.' },
+                503: { description: 'No frontend is connected.' }
+            }
+        }, ({ body }) => this.createSession(body));
+        router.post('/:id/open', {
+            operationId: 'openChatSession',
+            summary: 'Show the session in the chat view of a connected frontend, restoring it first if necessary.',
+            params: { id: SESSION_ID_PARAM },
+            responses: {
+                204: { description: 'The session is shown in a frontend.' },
+                404: { description: 'The session is unknown to all connected frontends.' }
+            }
+        }, async ({ params }) =>
+            await this.registry.openSession(params.id) ? RestResult.noContent() : RestResult.notFound());
+        router.post('/:id/restore', {
+            operationId: 'restoreChatSession',
+            summary: 'Restore the session in a connected frontend without focusing it, and return its detail.',
+            params: { id: SESSION_ID_PARAM },
+            responses: {
+                200: { description: 'The detail of the restored session.', schema: ExternalChatSessionDetail.SCHEMA },
+                404: { description: 'The session is unknown to all connected frontends.' }
+            }
+        }, async ({ params }) => {
+            const session = await this.registry.restoreSession(params.id);
+            return session ? RestResult.ok(session) : RestResult.notFound();
+        });
+        router.post('/:id/prompt', {
+            operationId: 'promptChatSession',
+            summary: 'Send a prompt to the session, restoring it first if necessary.',
+            bodySchema: ExternalChatPrompt.SCHEMA,
+            params: { id: SESSION_ID_PARAM },
+            responses: {
+                202: { description: 'The prompt was submitted; follow the progress via the event stream or the read endpoints.', schema: PROMPT_ACCEPTED_SCHEMA },
+                404: { description: 'The session is unknown to all connected frontends.' },
+                409: { description: 'A request is in progress and `interrupt` was not set, or no agent is available.' }
+            }
+        }, ({ params, body }) => this.sendPrompt(params.id, body));
+    }
+
+    protected async createSession(request: ExternalChatSessionCreateRequest): Promise<RestResult> {
+        const result = await this.registry.createSession(request);
+        if ('created' in result) {
+            return RestResult.created(result.created);
+        }
+        switch (result.failure) {
+            case 'unknownAgent':
+                return RestResult.badRequest('unknown agent');
+            case 'noAgent':
+                return RestResult.conflict('no agent available');
+            case 'noFrontend':
+                return RestResult.error(503, 'no frontend connected');
+            case 'workspaceNotFound':
+                return RestResult.notFound('workspace not found');
+            case 'ambiguousWorkspace':
+                return RestResult.conflict('ambiguous workspace');
+        }
+    }
+
+    protected async sendPrompt(sessionId: string, prompt: ExternalChatPrompt): Promise<RestResult> {
+        const result = await this.registry.sendPrompt(sessionId, prompt);
+        if (!result) {
+            return RestResult.notFound();
+        }
+        if ('sent' in result) {
+            return RestResult.accepted(result.sent);
+        }
+        return RestResult.conflict(result.failure === 'busy' ? 'busy' : 'no agent available');
+    }
+}