@cloudcli-ai/cloudcli 1.36.2 → 1.37.0

package/server/modules/plugins/plugins.service.ts

@@ -0,0 +1,147 @@
+import { AppError } from '@/shared/utils.js';
+
+type PluginManifest = Record<string, unknown> & {
+  name: string;
+  dirName?: string;
+  enabled?: boolean;
+  server?: unknown;
+};
+
+type PluginConfig = Record<string, { enabled?: boolean; secrets?: Record<string, unknown> }>;
+
+type PluginDependencies = {
+  scanPlugins(): PluginManifest[];
+  readConfig(): PluginConfig;
+  saveConfig(config: PluginConfig): void;
+  getPluginDirectory(pluginName: string): string | null;
+  getPluginsDirectory(): string;
+  resolveAsset(pluginName: string, assetPath: string): string | null;
+  assetIsFile(assetPath: string): boolean;
+  contentType(assetPath: string): string;
+  install(url: string): Promise<unknown>;
+  update(pluginName: string): Promise<unknown>;
+  uninstall(pluginName: string): Promise<unknown>;
+  startServer(pluginName: string, pluginDirectory: string, serverConfig: unknown): Promise<number>;
+  stopServer(pluginName: string): Promise<void>;
+  getServerPort(pluginName: string): number | undefined;
+  isServerRunning(pluginName: string): boolean;
+  joinPath(...parts: string[]): string;
+  logError(message: string, error: unknown): void;
+};
+
+function validatePluginName(pluginName: string): void {
+  if (!/^[a-zA-Z0-9_-]+$/.test(pluginName)) {
+    throw new AppError('Invalid plugin name', { code: 'INVALID_PLUGIN_NAME', statusCode: 400 });
+  }
+}
+
+function normalizePluginManifest(value: unknown): PluginManifest {
+  if (typeof value !== 'object' || value === null) {
+    throw new AppError('Plugin manifest is invalid', {
+      code: 'INVALID_PLUGIN_MANIFEST',
+      statusCode: 400,
+    });
+  }
+  const manifest = value as Record<string, unknown>;
+  if (typeof manifest.name !== 'string') {
+    throw new AppError('Plugin manifest is missing its name', {
+      code: 'INVALID_PLUGIN_MANIFEST',
+      statusCode: 400,
+    });
+  }
+  return manifest as PluginManifest;
+}
+
+/** Creates plugin-management workflows around loader and process adapters. */
+export function createPluginsService(dependencies: PluginDependencies) {
+  async function startServerIfAvailable(plugin: PluginManifest): Promise<void> {
+    if (!plugin.server || dependencies.isServerRunning(plugin.name)) return;
+    const pluginDirectory = dependencies.getPluginDirectory(plugin.name);
+    if (!pluginDirectory) return;
+    try {
+      await dependencies.startServer(plugin.name, pluginDirectory, plugin.server);
+    } catch (error) {
+      dependencies.logError(`Failed to start plugin server for ${plugin.name}`, error);
+    }
+  }
+
+  return {
+    list() {
+      return {
+        plugins: dependencies.scanPlugins().map((plugin) => ({
+          ...plugin,
+          serverRunning: plugin.server ? dependencies.isServerRunning(plugin.name) : false,
+        })),
+      };
+    },
+    getManifest(pluginName: string) {
+      validatePluginName(pluginName);
+      const plugin = dependencies.scanPlugins().find((candidate) => candidate.name === pluginName);
+      if (!plugin) throw new AppError('Plugin not found', { code: 'PLUGIN_NOT_FOUND', statusCode: 404 });
+      return plugin;
+    },
+    resolveAsset(pluginName: string, assetPath: string) {
+      validatePluginName(pluginName);
+      if (!assetPath) throw new AppError('No asset path specified', { code: 'PLUGIN_ASSET_REQUIRED', statusCode: 400 });
+      const resolvedPath = dependencies.resolveAsset(pluginName, assetPath);
+      if (!resolvedPath || !dependencies.assetIsFile(resolvedPath)) {
+        throw new AppError('Asset not found', { code: 'PLUGIN_ASSET_NOT_FOUND', statusCode: 404 });
+      }
+      return { path: resolvedPath, contentType: dependencies.contentType(resolvedPath) };
+    },
+    async setEnabled(pluginName: string, enabled: unknown) {
+      validatePluginName(pluginName);
+      if (typeof enabled !== 'boolean') {
+        throw new AppError('"enabled" must be a boolean', { code: 'INVALID_PLUGIN_ENABLED', statusCode: 400 });
+      }
+      const plugin = this.getManifest(pluginName);
+      const config = dependencies.readConfig();
+      config[pluginName] = { ...config[pluginName], enabled };
+      dependencies.saveConfig(config);
+      if (plugin.server && enabled) await startServerIfAvailable(plugin);
+      if (plugin.server && !enabled && dependencies.isServerRunning(pluginName)) {
+        await dependencies.stopServer(pluginName);
+      }
+      return { success: true, name: pluginName, enabled };
+    },
+    async install(urlInput: unknown) {
+      const url = typeof urlInput === 'string' ? urlInput.trim() : '';
+      if (!url || (!url.startsWith('https://') && !url.startsWith('git@'))) {
+        throw new AppError('URL must start with https:// or git@', { code: 'INVALID_PLUGIN_URL', statusCode: 400 });
+      }
+      const plugin = normalizePluginManifest(await dependencies.install(url));
+      await startServerIfAvailable(plugin);
+      return { success: true, plugin };
+    },
+    async update(pluginName: string) {
+      validatePluginName(pluginName);
+      const wasRunning = dependencies.isServerRunning(pluginName);
+      if (wasRunning) await dependencies.stopServer(pluginName);
+      const plugin = normalizePluginManifest(await dependencies.update(pluginName));
+      if (wasRunning) await startServerIfAvailable(plugin);
+      return { success: true, plugin };
+    },
+    async prepareRpc(pluginName: string) {
+      validatePluginName(pluginName);
+      let port = dependencies.getServerPort(pluginName);
+      if (!port) {
+        const plugin = this.getManifest(pluginName);
+        if (!plugin.server) throw new AppError('Plugin server is not running', { code: 'PLUGIN_SERVER_UNAVAILABLE', statusCode: 503 });
+        if (!plugin.enabled) throw new AppError('Plugin is disabled', { code: 'PLUGIN_DISABLED', statusCode: 503 });
+        const pluginDirectory = dependencies.joinPath(
+          dependencies.getPluginsDirectory(),
+          plugin.dirName ?? plugin.name,
+        );
+        port = await dependencies.startServer(pluginName, pluginDirectory, plugin.server);
+      }
+      const secrets = dependencies.readConfig()[pluginName]?.secrets ?? {};
+      return { port, secrets };
+    },
+    async uninstall(pluginName: string) {
+      validatePluginName(pluginName);
+      if (dependencies.isServerRunning(pluginName)) await dependencies.stopServer(pluginName);
+      await dependencies.uninstall(pluginName);
+      return { success: true, name: pluginName };
+    },
+  };
+}

package/server/modules/plugins/tests/plugins.service.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createPluginsService } from '../plugins.service.js';
+
+type Dependencies = Parameters<typeof createPluginsService>[0];
+
+function dependencies(overrides: Partial<Dependencies> = {}): Dependencies {
+  return {
+    scanPlugins: () => [], readConfig: () => ({}), saveConfig: () => undefined,
+    getPluginDirectory: () => null, getPluginsDirectory: () => '/plugins',
+    resolveAsset: () => null, assetIsFile: () => false, contentType: () => 'text/plain',
+    install: async () => ({ name: 'plugin', dirName: 'plugin' }),
+    update: async () => ({ name: 'plugin', dirName: 'plugin' }),
+    uninstall: async () => undefined, startServer: async () => 4000,
+    stopServer: async () => undefined, getServerPort: () => undefined,
+    isServerRunning: () => false, joinPath: (...parts) => parts.join('/'),
+    logError: () => undefined, ...overrides,
+  };
+}
+
+test('setEnabled persists configuration and starts an enabled plugin server', async () => {
+  const operations: string[] = [];
+  const service = createPluginsService(dependencies({
+    scanPlugins: () => [{ name: 'demo', dirName: 'demo', server: { entry: 'server.js' } }],
+    getPluginDirectory: () => '/plugins/demo',
+    saveConfig: () => operations.push('save'),
+    startServer: async () => { operations.push('start'); return 4000; },
+  }));
+  await service.setEnabled('demo', true);
+  assert.deepEqual(operations, ['save', 'start']);
+});

package/server/modules/projects/index.ts

@@ -3,4 +3,9 @@ export {
   getProjectsWithSessions,
 } from './services/projects-with-sessions-fetch.service.js';
 export { updateProjectDisplayName } from './services/project-management.service.js';
+// createProject: used by the worktrees module to register a worktree directory as a switchable project.
+export { createProject } from './services/project-management.service.js';
+// deleteOrArchiveProject: used by Projects routes and Worktrees cleanup to hide or permanently remove a project.
 export { deleteOrArchiveProject, deleteSessionJsonlFilesForProjectPath } from './services/project-delete.service.js';
+// restoreArchivedProject: used by the worktrees module to re-activate an archived project when its worktree is reopened.
+export { restoreArchivedProject } from './services/project-delete.service.js';

package/server/modules/providers/README.md

@@ -7,8 +7,10 @@ without guessing which files need to move.
 
 ## Current Provider Shape
 
-Every provider wrapper exposes five facets:
+Every provider wrapper exposes seven facets:
 
+- `runtime`
+- `models`
 - `auth`
 - `mcp`
 - `skills`
@@ -17,6 +19,8 @@ Every provider wrapper exposes five facets:
 
 These correspond to the shared interfaces in `server/shared/interfaces.ts`:
 
+- `IProviderRuntime`
+- `IProviderModels`
 - `IProviderAuth`
 - `IProviderMcp`
 - `IProviderSkills`
@@ -25,12 +29,16 @@ These correspond to the shared interfaces in `server/shared/interfaces.ts`:
 
 The services that consume them are:
 
+- `providerModelsService`
 - `providerAuthService`
 - `providerMcpService`
 - `providerSkillsService`
 - `sessionsService`
 - `sessionSynchronizerService`
 
+Live execution is consumed through `providerRuntimeService`, which resolves the
+provider-owned runtime through the same `providerRegistry` as every other facet.
+
 Current provider ids in this repo are:
 
 - `claude`
@@ -48,7 +56,9 @@ Each provider lives under its own folder in `server/modules/providers/list/`:
 ```text
 server/modules/providers/list/<provider>/
   <provider>.provider.ts
+  <provider>-runtime.provider.js
   <provider>-auth.provider.ts
+  <provider>-models.provider.ts
   <provider>-mcp.provider.ts
   <provider>-skills.provider.ts
   <provider>-sessions.provider.ts
@@ -57,10 +67,19 @@ server/modules/providers/list/<provider>/
 
 The existing provider folders are `claude`, `codex`, `cursor`, and `opencode`.
 
+Each provider wrapper owns its SDK/CLI runtime alongside its auth, model, and
+session facets. Runtime adapters receive registry-backed model and session
+lookups from `providerRuntimeService` at execution time instead of importing
+those services themselves. This keeps `providerRegistry` as the only provider
+mapping without creating a circular dependency. Application-level consumers
+import the service from `server/modules/providers/index.ts`.
+
 ## What Each Facet Does
 
 | Facet | Responsibility | Base / Service |
 | --- | --- | --- |
+| `runtime` | Run and abort live SDK/CLI sessions | `IProviderRuntime` -> `providerRuntimeService` |
+| `models` | Resolve supported and active models | `IProviderModels` -> `providerModelsService` |
 | `auth` | Report install/auth state for the provider runtime | `IProviderAuth` -> `providerAuthService` |
 | `mcp` | Read, list, write, and remove provider-native MCP config | `McpProvider` -> `providerMcpService` |
 | `skills` | Discover provider-native skill markdown files | `SkillsProvider` -> `providerSkillsService` |
@@ -79,8 +98,8 @@ The existing provider folders are `claude`, `codex`, `cursor`, and `opencode`.
 - Update `server/shared/types.ts` `LLMProvider`.
 - Update `src/types/app.ts` `LLMProvider` if the frontend should know about it.
 - Update `server/modules/providers/provider.routes.ts`.
-- Update `server/routes/agent.js` if the provider is launchable from the agent runtime.
-- Update `server/index.js` if the provider needs runtime boot or shutdown wiring.
+- Update `server/modules/agent/agent.routes.ts` if the provider is launchable from the agent runtime.
+- Update `server/index.ts` if the provider needs runtime boot or shutdown wiring.
 - Update the `PROVIDER_ORDER` list in `public/api-docs.html` if the provider should appear in the public API docs.
 - Update `src/components/chat/hooks/useChatProviderState.ts` and
   `src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx` if
@@ -91,6 +110,8 @@ The existing provider folders are `claude`, `codex`, `cursor`, and `opencode`.
 2. Create the wrapper class.
 
 - Add `server/modules/providers/list/<provider>/<provider>.provider.ts`.
+- Add `server/modules/providers/list/<provider>/<provider>-runtime.provider.js`
+  when the provider supports live SDK/CLI execution.
 - Extend `AbstractProvider`.
 - Expose readonly `auth`, `mcp`, `skills`, `sessions`, and `sessionSynchronizer`.
 - Call `super('<provider>')`.
@@ -198,8 +219,10 @@ Current session sync roots are:
 
 If the provider can run live chat sessions, update the runtime entrypoints too:
 
-- `server/routes/agent.js`
-- `server/index.js`
+- `server/modules/providers/list/<provider>/<provider>-runtime.provider.js`
+- `server/modules/providers/list/<provider>/<provider>.provider.ts`
+- `server/modules/agent/agent.routes.ts`
+- `server/index.ts`
 
 If the provider is visible in the UI, update:
 
@@ -214,19 +237,25 @@ If the provider is visible in the UI, update:
 ```ts
 import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
 import { <Provider>ProviderAuth } from './<provider>-auth.provider.js';
+import { <Provider>ProviderModels } from './<provider>-models.provider.js';
 import { <Provider>McpProvider } from './<provider>-mcp.provider.js';
+import { <provider>Runtime } from './<provider>-runtime.provider.js';
 import { <Provider>SkillsProvider } from './<provider>-skills.provider.js';
 import { <Provider>SessionsProvider } from './<provider>-sessions.provider.js';
 import { <Provider>SessionSynchronizer } from './<provider>-session-synchronizer.provider.js';
 import type {
   IProviderAuth,
   IProviderMcp,
+  IProviderModels,
+  IProviderRuntime,
   IProviderSessionSynchronizer,
   IProviderSessions,
   IProviderSkills,
 } from '@/shared/interfaces.js';
 
 export class <Provider>Provider extends AbstractProvider {
+  readonly runtime: IProviderRuntime = <provider>Runtime;
+  readonly models: IProviderModels = new <Provider>ProviderModels();
   readonly auth: IProviderAuth = new <Provider>ProviderAuth();
   readonly mcp: IProviderMcp = new <Provider>McpProvider();
   readonly skills: IProviderSkills = new <Provider>SkillsProvider();
@@ -290,15 +319,17 @@ Add a new provider "<provider>" using the current provider module architecture.
 
 Requirements:
 1) Create:
-   - server/modules/providers/list/<provider>/<provider>.provider.ts
+    - server/modules/providers/list/<provider>/<provider>.provider.ts
+    - server/modules/providers/list/<provider>/<provider>-runtime.provider.js
    - server/modules/providers/list/<provider>/<provider>-auth.provider.ts
+   - server/modules/providers/list/<provider>/<provider>-models.provider.ts
    - server/modules/providers/list/<provider>/<provider>-mcp.provider.ts
    - server/modules/providers/list/<provider>/<provider>-skills.provider.ts
    - server/modules/providers/list/<provider>/<provider>-sessions.provider.ts
    - server/modules/providers/list/<provider>/<provider>-session-synchronizer.provider.ts
 2) Register in:
-   - server/modules/providers/provider.registry.ts
-   - server/modules/providers/provider.routes.ts
+    - server/modules/providers/provider.registry.ts
+    - server/modules/providers/provider.routes.ts
    - server/shared/types.ts LLMProvider
    - src/types/app.ts LLMProvider
 3) Mirror the nearest existing provider implementation for file naming, style,
@@ -334,9 +365,10 @@ alongside the implementation.
 
 - Adding provider files but forgetting `provider.registry.ts` or
   `provider.routes.ts`.
+- Adding a live runtime without exposing it from the provider wrapper.
 - Updating backend provider ids but not `src/types/app.ts` or the frontend
   provider constants.
-- Omitting `skills` or `sessionSynchronizer` from the wrapper.
+- Omitting `runtime`, `skills`, or `sessionSynchronizer` from the wrapper.
 - Returning duplicate normalized message ids for split content.
 - Treating `limit === 0` as unbounded history.
 - Building file paths from raw session ids without validation.

package/server/modules/providers/index.ts

@@ -1,6 +1,10 @@
 export { sessionSynchronizerService } from './services/session-synchronizer.service.js';
 export { providerSkillsService } from './services/skills.service.js';
 export { providerMcpService } from './services/mcp.service.js';
+export { providerRuntimeService } from './services/provider-runtime.service.js';
+
+// providerModelsService: used by Commands to list models and resolve the active session model.
+export { providerModelsService } from './services/provider-models.service.js';
 
 export { initializeSessionsWatcher } from './services/sessions-watcher.service.js';
 export { closeSessionsWatcher } from './services/sessions-watcher.service.js';

package/server/modules/providers/list/claude/claude-auth.provider.ts

@@ -100,6 +100,14 @@ export class ClaudeProviderAuth implements IProviderAuth {
       return { authenticated: true, email: 'Configured via settings.json', method: 'api_key' };
     }
 
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN?.trim()) {
+      return { authenticated: true, email: 'OAuth Token (long-lived)', method: 'environment' };
+    }
+
+    if (readOptionalString(settingsEnv.CLAUDE_CODE_OAUTH_TOKEN)) {
+      return { authenticated: true, email: 'OAuth Token (long-lived)', method: 'environment' };
+    }
+
     try {
       const credPath = path.join(os.homedir(), '.claude', '.credentials.json');
       const content = await readFile(credPath, 'utf8');

package/server/modules/providers/list/claude/claude-models.provider.ts

@@ -3,16 +3,11 @@ import { readFile } from 'node:fs/promises';
 import { sessionsDb } from '@/modules/database/index.js';
 import type { IProviderModels } from '@/shared/interfaces.js';
 import type {
-  ProviderChangeActiveModelInput,
   ProviderCurrentActiveModel,
   ProviderModelOption,
   ProviderModelsDefinition,
-  ProviderSessionActiveModelChange,
 } from '@/shared/types.js';
-import {
-  buildDefaultProviderCurrentActiveModel,
-  writeProviderSessionActiveModelChange,
-} from '@/shared/utils.js';
+import { buildDefaultProviderCurrentActiveModel } from '@/shared/utils.js';
 
 export const CLAUDE_FALLBACK_MODELS: ProviderModelsDefinition = {
   OPTIONS: [
@@ -264,10 +259,4 @@ export class ClaudeProviderModels implements IProviderModels {
 
     return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
   }
-
-  async changeActiveModel(
-    input: ProviderChangeActiveModelInput,
-  ): Promise<ProviderSessionActiveModelChange> {
-    return writeProviderSessionActiveModelChange('claude', input);
-  }
 }