feat(openshell): add OpenshellCli wrapper for sandbox and gateway operations

extensions/openshell/src/manager/openshell-cli-manager.ts

@@ -17,84 +17,125 @@
  ***********************************************************************/
 
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 import type { CliToolInstallationSource, Disposable, ExtensionContext } from '@openkaiden/api';
 import * as extensionApi from '@openkaiden/api';
 import { inject, injectable } from 'inversify';
 
 import { ExtensionContextSymbol } from '/@/inject/symbol';
 
+interface BinaryDiscoveryResult {
+  path: string;
+  version: string;
+  installationSource: CliToolInstallationSource;
+}
+
 @injectable()
 export class OpenshellCliManager implements Disposable {
   @inject(ExtensionContextSymbol)
   private extensionContext!: ExtensionContext;
 
+  #registeredPath: string | undefined;
+
+  getRegisteredPath(): string | undefined {
+    return this.#registeredPath;
+  }
+
   async init(): Promise<void> {
+    const cliResult = await this.discoverBinary('openshell', 'openshell.binary.path');
+    if (!cliResult) {
+      console.warn('[openshell] CLI not found, skipping registration');
+      return;
+    }
+
+    this.#registeredPath = cliResult.path;
+    this.registerCliTool('openshell', 'OpenShell', 'OpenShell CLI for managing sandboxed workspaces', cliResult);
+
+    const gatewayResult = await this.discoverGatewayBinary(cliResult.path);
+    if (gatewayResult) {
+      this.registerCliTool(
+        'openshell-gateway',
+        'OpenShell Gateway',
+        'OpenShell Gateway server for sandbox orchestration',
+        gatewayResult,
+      );
+    } else {
+      console.warn('[openshell-gateway] binary not found, skipping registration');
+    }
+  }
+
+  dispose(): void {}
+
+  private registerCliTool(
+    name: string,
+    displayName: string,
+    markdownDescription: string,
+    result: BinaryDiscoveryResult,
+  ): void {
+    const cliTool = extensionApi.cli.createCliTool({
+      name,
+      displayName,
+      markdownDescription,
+      images: {},
+      version: result.version,
+      path: result.path,
+      installationSource: result.installationSource,
+    });
+    this.extensionContext.subscriptions.push(cliTool);
+    console.log(`[${name}] registered at ${result.path} (v${result.version})`);
+  }
+
+  private async discoverBinary(binaryBaseName: string, configKey: string): Promise<BinaryDiscoveryResult | undefined> {
     const binDir = join(this.extensionContext.storagePath, 'bin');
-    const binaryName = 'openshell';
+    const binaryName = extensionApi.env.isWindows ? `${binaryBaseName}.exe` : binaryBaseName;
     const localBinaryPath = join(binDir, binaryName);
 
-    let binaryPath: string | undefined;
-    let version: string | undefined;
-    let installationSource: CliToolInstallationSource = 'external';
-
-    const customPath = this.getCustomBinaryPath();
+    const customPath = extensionApi.configuration.getConfiguration('openshell').get<string>(configKey) ?? undefined;
     if (customPath && existsSync(customPath)) {
-      version = await this.getVersion(customPath);
+      const version = await this.getVersion(customPath);
       if (version) {
-        binaryPath = customPath;
-        installationSource = 'external';
-        console.log(`[openshell] using custom binary path: ${customPath}`);
-      } else {
-        console.warn(`[openshell] custom binary at ${customPath} failed to report a version`);
+        console.log(`[${binaryBaseName}] using custom binary path: ${customPath}`);
+        return { path: customPath, version, installationSource: 'external' };
       }
+      console.warn(`[${binaryBaseName}] custom binary at ${customPath} failed to report a version`);
     }
 
-    if (!binaryPath && existsSync(localBinaryPath)) {
-      version = await this.getVersion(localBinaryPath);
+    if (existsSync(localBinaryPath)) {
+      const version = await this.getVersion(localBinaryPath);
       if (version) {
-        binaryPath = localBinaryPath;
-        installationSource = 'extension';
-        console.log('[openshell] binary found in extension storage');
-      } else {
-        console.warn(`[openshell] binary exists at ${localBinaryPath} but failed to report a version`);
-      }
-    }
-
-    if (!binaryPath) {
-      const systemResult = await this.findOnPath();
-      if (systemResult) {
-        binaryPath = systemResult.path;
-        version = systemResult.version;
-        installationSource = 'external';
-        console.log('[openshell] binary found in system PATH');
-      } else {
-        console.warn('[openshell] not found in system PATH');
+        console.log(`[${binaryBaseName}] binary found in extension storage`);
+        return { path: localBinaryPath, version, installationSource: 'extension' };
       }
+      console.warn(`[${binaryBaseName}] binary exists at ${localBinaryPath} but failed to report a version`);
     }
 
-    if (!binaryPath) {
-      console.warn('[openshell] CLI not found, skipping registration');
-      return;
+    const systemResult = await this.findOnPath(binaryBaseName);
+    if (systemResult) {
+      console.log(`[${binaryBaseName}] binary found in system PATH`);
+      return { path: systemResult.path, version: systemResult.version, installationSource: 'external' };
     }
 
-    const cliTool = extensionApi.cli.createCliTool({
-      name: 'openshell',
-      displayName: 'OpenShell',
-      markdownDescription: 'OpenShell CLI for managing sandboxed workspaces',
-      images: {},
-      version,
-      path: binaryPath,
-      installationSource,
-    });
-    this.extensionContext.subscriptions.push(cliTool);
+    return undefined;
   }
 
-  dispose(): void {}
+  private async discoverGatewayBinary(cliPath: string): Promise<BinaryDiscoveryResult | undefined> {
+    const result = await this.discoverBinary('openshell-gateway', 'openshell.gateway.binary.path');
+    if (result) {
+      return result;
+    }
 
-  private getCustomBinaryPath(): string | undefined {
-    return extensionApi.configuration.getConfiguration('openshell').get<string>('binary.path') ?? undefined;
+    const gatewayName = extensionApi.env.isWindows ? 'openshell-gateway.exe' : 'openshell-gateway';
+    const siblingPath = join(dirname(cliPath), gatewayName);
+    if (existsSync(siblingPath)) {
+      const version = await this.getVersion(siblingPath);
+      if (version) {
+        console.log('[openshell-gateway] binary found alongside openshell CLI');
+        return { path: siblingPath, version, installationSource: 'external' };
+      }
+    }
+
+    return undefined;
   }
 
   private parseVersion(output: string): string | undefined {
@@ -112,12 +153,12 @@ export class OpenshellCliManager implements Disposable {
     }
   }
 
-  private async findOnPath(): Promise<{ version: string; path: string } | undefined> {
+  private async findOnPath(binaryName: string): Promise<{ version: string; path: string } | undefined> {
     try {
-      const result = await extensionApi.process.exec('openshell', ['--version']);
+      const result = await extensionApi.process.exec(binaryName, ['--version']);
       const version = this.parseVersion(result.stdout || result.stderr);
       if (version) {
-        const resolvedPath = await this.resolveFromPath();
+        const resolvedPath = await this.resolveFromPath(binaryName);
         return { version, path: resolvedPath };
       }
     } catch {
@@ -126,9 +167,9 @@ export class OpenshellCliManager implements Disposable {
     return undefined;
   }
 
-  private async resolveFromPath(): Promise<string> {
+  private async resolveFromPath(binaryName: string): Promise<string> {
     const cmd = extensionApi.env.isWindows ? 'where' : 'which';
-    const result = await extensionApi.process.exec(cmd, ['openshell']);
+    const result = await extensionApi.process.exec(cmd, [binaryName]);
     return result.stdout.trim().split(/\r?\n/)[0];
   }
 }

packages/api/src/openshell-gateway-info.ts

@@ -0,0 +1,74 @@
+/**********************************************************************
+ * Copyright (C) 2026 Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ***********************************************************************/
+
+import z from 'zod';
+
+export const GatewayInfoSchema = z.object({
+  name: z.string(),
+  endpoint: z.string(),
+  active: z.boolean().optional(),
+  auth: z.string().optional(),
+  type: z.string().optional(),
+});
+
+export type GatewayInfo = z.output<typeof GatewayInfoSchema>;
+
+export const SandboxInfoSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  phase: z.string(),
+  created_at: z.string().optional(),
+  current_policy_version: z.number().optional(),
+  labels: z.record(z.string(), z.string()).optional(),
+  resource_version: z.number().optional(),
+});
+
+export type SandboxInfo = z.output<typeof SandboxInfoSchema>;
+
+export interface CreateSandboxOptions {
+  name?: string;
+  gateway?: string;
+  from?: string;
+  gpu?: boolean;
+  gpuDevice?: string;
+  cpu?: string;
+  memory?: string;
+  providers?: string[];
+  labels?: Record<string, string>;
+  command?: string[];
+}
+
+export interface GatewayAddOptions {
+  endpoint: string;
+  name?: string;
+  /** SSH destination for remote mTLS gateway (conflicts with `local`). */
+  remote?: string;
+  /** Use local mTLS gateway in Docker (conflicts with `remote`). */
+  local?: boolean;
+}
+
+export interface OpenshellGatewayStartOptions {
+  port?: number;
+  bindAddress?: string;
+  disableTls?: boolean;
+}
+
+export interface GatewaySandboxes {
+  gateway: GatewayInfo;
+  sandboxes: SandboxInfo[];
+}

packages/main/src/plugin/index.ts

@@ -70,6 +70,8 @@ import { MCPIPCHandler } from '/@/plugin/mcp/mcp-ipc-handler.js';
 import { MCPManager } from '/@/plugin/mcp/mcp-manager.js';
 import { MenuRegistry } from '/@/plugin/menu-registry.js';
 import { NavigationManager } from '/@/plugin/navigation/navigation-manager.js';
+import { OpenshellCli } from '/@/plugin/openshell-cli/openshell-cli.js';
+import { OpenshellGateway } from '/@/plugin/openshell-cli/openshell-gateway.js';
 import { RagEnvironmentRegistry } from '/@/plugin/rag-environment-registry.js';
 import { SchedulerRegistry } from '/@/plugin/scheduler/scheduler-registry.js';
 import { SecretManager } from '/@/plugin/secret-manager/secret-manager.js';
@@ -588,6 +590,8 @@ export class PluginSystem {
     container.bind<CliToolRegistry>(CliToolRegistry).toSelf().inSingletonScope();
     container.bind<AgentRegistry>(AgentRegistry).toSelf().inSingletonScope();
     container.bind<KdnCli>(KdnCli).toSelf().inSingletonScope();
+    container.bind<OpenshellCli>(OpenshellCli).toSelf().inSingletonScope();
+    container.bind<OpenshellGateway>(OpenshellGateway).toSelf().inSingletonScope();
     container.bind<AgentWorkspaceManager>(AgentWorkspaceManager).toSelf().inSingletonScope();
     container.bind<SecretManager>(SecretManager).toSelf().inSingletonScope();
     container.bind<FlowManager>(FlowManager).toSelf().inSingletonScope();
@@ -3744,6 +3748,9 @@ export class PluginSystem {
       apiSender.send('extensions-started');
       this.markAsExtensionsStarted();
     }
+    const openshellGateway = container.get<OpenshellGateway>(OpenshellGateway);
+    openshellGateway.init().catch((err: unknown) => console.error('Unable to initialize openshell gateway', err));
+
     extensionsUpdater.init().catch((err: unknown) => console.error('Unable to perform extension updates', err));
     autoStartEngine.start().catch((err: unknown) => console.error('Unable to perform autostart', err));
     await exploreFeatures.init();