forked from OpenHands/OpenHands
-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathbase.py
More file actions
1065 lines (898 loc) Β· 38.8 KB
/
base.py
File metadata and controls
1065 lines (898 loc) Β· 38.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
import asyncio
import atexit
import copy
import json
import os
import random
import shutil
import string
import tempfile
from abc import abstractmethod
from pathlib import Path
from types import MappingProxyType
from typing import Callable, cast
from zipfile import ZipFile
import httpx
from openhands.core.config import OpenHandsConfig, SandboxConfig
from openhands.core.config.mcp_config import MCPConfig, MCPStdioServerConfig
from openhands.core.exceptions import (
AgentRuntimeDisconnectedError,
)
from openhands.core.logger import openhands_logger as logger
from openhands.events import EventSource, EventStream, EventStreamSubscriber
from openhands.events.action import (
Action,
ActionConfirmationStatus,
AgentThinkAction,
BrowseInteractiveAction,
BrowseURLAction,
CmdRunAction,
FileEditAction,
FileReadAction,
FileWriteAction,
IPythonRunCellAction,
)
from openhands.events.action.mcp import MCPAction
from openhands.events.event import Event
from openhands.events.observation import (
AgentThinkObservation,
CmdOutputObservation,
ErrorObservation,
FileReadObservation,
NullObservation,
Observation,
UserRejectObservation,
)
from openhands.events.serialization.action import ACTION_TYPE_TO_CLASS
from openhands.integrations.provider import (
PROVIDER_TOKEN_TYPE,
ProviderHandler,
ProviderType,
)
from openhands.integrations.service_types import AuthenticationError
from openhands.microagent import (
BaseMicroagent,
load_microagents_from_dir,
)
from openhands.runtime.plugins import (
JupyterRequirement,
PluginRequirement,
VSCodeRequirement,
)
from openhands.runtime.runtime_status import RuntimeStatus
from openhands.runtime.utils.edit import FileEditRuntimeMixin
from openhands.runtime.utils.git_handler import CommandResult, GitHandler
from openhands.utils.async_utils import (
GENERAL_TIMEOUT,
call_async_from_sync,
call_sync_from_async,
)
def _default_env_vars(sandbox_config: SandboxConfig) -> dict[str, str]:
ret = {}
for key in os.environ:
if key.startswith('SANDBOX_ENV_'):
sandbox_key = key.removeprefix('SANDBOX_ENV_')
ret[sandbox_key] = os.environ[key]
if sandbox_config.enable_auto_lint:
ret['ENABLE_AUTO_LINT'] = 'true'
return ret
class Runtime(FileEditRuntimeMixin):
"""Abstract base class for agent runtime environments.
This is an extension point in OpenHands that allows applications to customize how
agents interact with the external environment. The runtime provides a sandbox with:
- Bash shell access
- Browser interaction
- Filesystem operations
- Git operations
- Environment variable management
Applications can substitute their own implementation by:
1. Creating a class that inherits from Runtime
2. Implementing all required methods
3. Setting the runtime name in configuration or using get_runtime_cls()
The class is instantiated via get_impl() in get_runtime_cls().
Built-in implementations include:
- DockerRuntime: Containerized environment using Docker
- RemoteRuntime: Remote execution environment
- LocalRuntime: Local execution for development
- KubernetesRuntime: Kubernetes-based execution environment
- CLIRuntime: Command-line interface runtime
Args:
sid: Session ID that uniquely identifies the current user session
"""
sid: str
config: OpenHandsConfig
initial_env_vars: dict[str, str]
attach_to_existing: bool
status_callback: Callable[[str, RuntimeStatus, str], None] | None
runtime_status: RuntimeStatus | None
_runtime_initialized: bool = False
def __init__(
self,
config: OpenHandsConfig,
event_stream: EventStream,
sid: str = 'default',
plugins: list[PluginRequirement] | None = None,
env_vars: dict[str, str] | None = None,
status_callback: Callable[[str, RuntimeStatus, str], None] | None = None,
attach_to_existing: bool = False,
headless_mode: bool = False,
user_id: str | None = None,
git_provider_tokens: PROVIDER_TOKEN_TYPE | None = None,
):
self.git_handler = GitHandler(
execute_shell_fn=self._execute_shell_fn_git_handler,
create_file_fn=self._create_file_fn_git_handler,
)
self.sid = sid
self.event_stream = event_stream
if event_stream:
event_stream.subscribe(
EventStreamSubscriber.RUNTIME, self.on_event, self.sid
)
self.plugins = (
copy.deepcopy(plugins) if plugins is not None and len(plugins) > 0 else []
)
# add VSCode plugin if not in headless mode
if not headless_mode:
self.plugins.append(VSCodeRequirement())
self.status_callback = status_callback
self.attach_to_existing = attach_to_existing
self.config = copy.deepcopy(config)
atexit.register(self.close)
self.initial_env_vars = _default_env_vars(config.sandbox)
if env_vars is not None:
self.initial_env_vars.update(env_vars)
self.provider_handler = ProviderHandler(
provider_tokens=git_provider_tokens
or cast(PROVIDER_TOKEN_TYPE, MappingProxyType({})),
external_auth_id=user_id,
external_token_manager=True,
)
raw_env_vars: dict[str, str] = call_async_from_sync(
self.provider_handler.get_env_vars, GENERAL_TIMEOUT, True, None, False
)
self.initial_env_vars.update(raw_env_vars)
self._vscode_enabled = any(
isinstance(plugin, VSCodeRequirement) for plugin in self.plugins
)
# Load mixins
FileEditRuntimeMixin.__init__(
self, enable_llm_editor=config.get_agent_config().enable_llm_editor
)
self.user_id = user_id
self.git_provider_tokens = git_provider_tokens
self.runtime_status = None
@property
def runtime_initialized(self) -> bool:
return self._runtime_initialized
def setup_initial_env(self) -> None:
if self.attach_to_existing:
return
logger.debug(f'Adding env vars: {self.initial_env_vars.keys()}')
self.add_env_vars(self.initial_env_vars)
if self.config.sandbox.runtime_startup_env_vars:
self.add_env_vars(self.config.sandbox.runtime_startup_env_vars)
def close(self) -> None:
"""
This should only be called by conversation manager or closing the session.
If called for instance by error handling, it could prevent recovery.
"""
pass
@classmethod
async def delete(cls, conversation_id: str) -> None:
pass
def log(self, level: str, message: str) -> None:
message = f'[runtime {self.sid}] {message}'
getattr(logger, level)(message, stacklevel=2)
def set_runtime_status(
self, runtime_status: RuntimeStatus, msg: str = '', level: str = 'info'
):
"""Sends a status message if the callback function was provided."""
self.runtime_status = runtime_status
if self.status_callback:
self.status_callback(level, runtime_status, msg)
# ====================================================================
def add_env_vars(self, env_vars: dict[str, str]) -> None:
env_vars = {key.upper(): value for key, value in env_vars.items()}
# Add env vars to the IPython shell (if Jupyter is used)
if any(isinstance(plugin, JupyterRequirement) for plugin in self.plugins):
code = 'import os\n'
for key, value in env_vars.items():
# Note: json.dumps gives us nice escaping for free
code += f'os.environ["{key}"] = {json.dumps(value)}\n'
code += '\n'
self.run_ipython(IPythonRunCellAction(code))
# Note: we don't log the vars values, they're leaking info
logger.debug('Added env vars to IPython')
# Check if we're on Windows
import os
import sys
is_windows = os.name == 'nt' or sys.platform == 'win32'
if is_windows:
# Add env vars using PowerShell commands for Windows
cmd = ''
for key, value in env_vars.items():
# Use PowerShell's $env: syntax for environment variables
# Note: json.dumps gives us nice escaping for free
cmd += f'$env:{key} = {json.dumps(value)}; '
if not cmd:
return
cmd = cmd.strip()
logger.debug('Adding env vars to PowerShell') # don't log the values
obs = self.run(CmdRunAction(cmd))
if not isinstance(obs, CmdOutputObservation) or obs.exit_code != 0:
raise RuntimeError(
f'Failed to add env vars [{env_vars.keys()}] to environment: {obs.content}'
)
# We don't add to profile persistence on Windows as it's more complex
# and varies between PowerShell versions
logger.debug(f'Added env vars to PowerShell session: {env_vars.keys()}')
else:
# Original bash implementation for Unix systems
cmd = ''
bashrc_cmd = ''
for key, value in env_vars.items():
# Note: json.dumps gives us nice escaping for free
cmd += f'export {key}={json.dumps(value)}; '
# Add to .bashrc if not already present
bashrc_cmd += f'grep -q "^export {key}=" ~/.bashrc || echo "export {key}={json.dumps(value)}" >> ~/.bashrc; '
if not cmd:
return
cmd = cmd.strip()
logger.debug('Adding env vars to bash') # don't log the values
obs = self.run(CmdRunAction(cmd))
if not isinstance(obs, CmdOutputObservation) or obs.exit_code != 0:
raise RuntimeError(
f'Failed to add env vars [{env_vars.keys()}] to environment: {obs.content}'
)
# Add to .bashrc for persistence
bashrc_cmd = bashrc_cmd.strip()
logger.debug(f'Adding env var to .bashrc: {env_vars.keys()}')
obs = self.run(CmdRunAction(bashrc_cmd))
if not isinstance(obs, CmdOutputObservation) or obs.exit_code != 0:
raise RuntimeError(
f'Failed to add env vars [{env_vars.keys()}] to .bashrc: {obs.content}'
)
def on_event(self, event: Event) -> None:
if isinstance(event, Action):
asyncio.get_event_loop().run_until_complete(self._handle_action(event))
async def _export_latest_git_provider_tokens(self, event: Action) -> None:
"""
Refresh runtime provider tokens when agent attemps to run action with provider token
"""
if not self.user_id:
return
providers_called = ProviderHandler.check_cmd_action_for_provider_token_ref(
event
)
if not providers_called:
return
logger.info(f'Fetching latest provider tokens for runtime: {self.sid}')
env_vars = await self.provider_handler.get_env_vars(
providers=providers_called, expose_secrets=False, get_latest=True
)
if len(env_vars) == 0:
return
try:
if self.event_stream:
await self.provider_handler.set_event_stream_secrets(
self.event_stream, env_vars=env_vars
)
self.add_env_vars(self.provider_handler.expose_env_vars(env_vars))
except Exception as e:
logger.warning(
f'Failed export latest github token to runtime: {self.sid}, {e}'
)
async def _handle_action(self, event: Action) -> None:
if event.timeout is None:
# We don't block the command if this is a default timeout action
event.set_hard_timeout(self.config.sandbox.timeout, blocking=False)
assert event.timeout is not None
try:
await self._export_latest_git_provider_tokens(event)
if isinstance(event, MCPAction):
observation: Observation = await self.call_tool_mcp(event)
else:
observation = await call_sync_from_async(self.run_action, event)
except PermissionError as e:
# Handle PermissionError specially - convert to ErrorObservation
# so the agent can receive feedback and continue execution
observation = ErrorObservation(content=str(e))
except (httpx.NetworkError, AgentRuntimeDisconnectedError) as e:
runtime_status = RuntimeStatus.ERROR_RUNTIME_DISCONNECTED
error_message = f'{type(e).__name__}: {str(e)}'
self.log('error', f'Unexpected error while running action: {error_message}')
self.log('error', f'Problematic action: {str(event)}')
self.set_runtime_status(runtime_status, error_message, level='error')
return
except Exception as e:
runtime_status = RuntimeStatus.ERROR
error_message = f'{type(e).__name__}: {str(e)}'
self.log('error', f'Unexpected error while running action: {error_message}')
self.log('error', f'Problematic action: {str(event)}')
self.set_runtime_status(runtime_status, error_message, level='error')
return
observation._cause = event.id # type: ignore[attr-defined]
observation.tool_call_metadata = event.tool_call_metadata
# this might be unnecessary, since source should be set by the event stream when we're here
source = event.source if event.source else EventSource.AGENT
if isinstance(observation, NullObservation):
# don't add null observations to the event stream
return
self.event_stream.add_event(observation, source) # type: ignore[arg-type]
async def clone_or_init_repo(
self,
git_provider_tokens: PROVIDER_TOKEN_TYPE | None,
selected_repository: str | None,
selected_branch: str | None,
) -> str:
if not selected_repository:
if self.config.init_git_in_empty_workspace:
logger.debug(
'No repository selected. Initializing a new git repository in the workspace.'
)
action = CmdRunAction(
command=f'git init && git config --global --add safe.directory {self.workspace_root}'
)
await call_sync_from_async(self.run_action, action)
else:
logger.info(
'In workspace mount mode, not initializing a new git repository.'
)
return ''
remote_repo_url = await self.provider_handler.get_authenticated_git_url(
selected_repository
)
if not remote_repo_url:
raise ValueError('Missing either Git token or valid repository')
if self.status_callback:
self.status_callback(
'info', RuntimeStatus.SETTING_UP_WORKSPACE, 'Setting up workspace...'
)
dir_name = selected_repository.split('/')[-1]
# Generate a random branch name to avoid conflicts
random_str = ''.join(
random.choices(string.ascii_lowercase + string.digits, k=8)
)
openhands_workspace_branch = f'openhands-workspace-{random_str}'
# Clone repository command
clone_command = f'git clone {remote_repo_url} {dir_name}'
# Checkout to appropriate branch
checkout_command = (
f'git checkout {selected_branch}'
if selected_branch
else f'git checkout -b {openhands_workspace_branch}'
)
clone_action = CmdRunAction(command=clone_command)
await call_sync_from_async(self.run_action, clone_action)
cd_checkout_action = CmdRunAction(
command=f'cd {dir_name} && {checkout_command}'
)
action = cd_checkout_action
self.log('info', f'Cloning repo: {selected_repository}')
await call_sync_from_async(self.run_action, action)
return dir_name
def maybe_run_setup_script(self):
"""Run .openhands/setup.sh if it exists in the workspace or repository."""
setup_script = '.openhands/setup.sh'
read_obs = self.read(FileReadAction(path=setup_script))
if isinstance(read_obs, ErrorObservation):
return
if self.status_callback:
self.status_callback(
'info', RuntimeStatus.SETTING_UP_WORKSPACE, 'Setting up workspace...'
)
# setup scripts time out after 10 minutes
action = CmdRunAction(
f'chmod +x {setup_script} && source {setup_script}',
blocking=True,
hidden=True,
)
action.set_hard_timeout(600)
# Add the action to the event stream as an ENVIRONMENT event
source = EventSource.ENVIRONMENT
self.event_stream.add_event(action, source)
# Execute the action
self.run_action(action)
@property
def workspace_root(self) -> Path:
"""Return the workspace root path."""
return Path(self.config.workspace_mount_path_in_sandbox)
def maybe_setup_git_hooks(self):
"""Set up git hooks if .openhands/pre-commit.sh exists in the workspace or repository."""
pre_commit_script = '.openhands/pre-commit.sh'
read_obs = self.read(FileReadAction(path=pre_commit_script))
if isinstance(read_obs, ErrorObservation):
return
if self.status_callback:
self.status_callback(
'info', RuntimeStatus.SETTING_UP_GIT_HOOKS, 'Setting up git hooks...'
)
# Ensure the git hooks directory exists
action = CmdRunAction('mkdir -p .git/hooks')
obs = self.run_action(action)
if isinstance(obs, CmdOutputObservation) and obs.exit_code != 0:
self.log('error', f'Failed to create git hooks directory: {obs.content}')
return
# Make the pre-commit script executable
action = CmdRunAction(f'chmod +x {pre_commit_script}')
obs = self.run_action(action)
if isinstance(obs, CmdOutputObservation) and obs.exit_code != 0:
self.log(
'error', f'Failed to make pre-commit script executable: {obs.content}'
)
return
# Check if there's an existing pre-commit hook
pre_commit_hook = '.git/hooks/pre-commit'
pre_commit_local = '.git/hooks/pre-commit.local'
# Read the existing pre-commit hook if it exists
read_obs = self.read(FileReadAction(path=pre_commit_hook))
if not isinstance(read_obs, ErrorObservation):
# If the existing hook wasn't created by OpenHands, preserve it
if 'This hook was installed by OpenHands' not in read_obs.content:
self.log('info', 'Preserving existing pre-commit hook')
# Move the existing hook to pre-commit.local
action = CmdRunAction(f'mv {pre_commit_hook} {pre_commit_local}')
obs = self.run_action(action)
if isinstance(obs, CmdOutputObservation) and obs.exit_code != 0:
self.log(
'error',
f'Failed to preserve existing pre-commit hook: {obs.content}',
)
return
# Make it executable
action = CmdRunAction(f'chmod +x {pre_commit_local}')
obs = self.run_action(action)
if isinstance(obs, CmdOutputObservation) and obs.exit_code != 0:
self.log(
'error',
f'Failed to make preserved hook executable: {obs.content}',
)
return
# Create the pre-commit hook that calls our script
pre_commit_hook_content = f"""#!/bin/bash
# This hook was installed by OpenHands
# It calls the pre-commit script in the .openhands directory
if [ -x "{pre_commit_script}" ]; then
source "{pre_commit_script}"
exit $?
else
echo "Warning: {pre_commit_script} not found or not executable"
exit 0
fi
"""
# Write the pre-commit hook
write_obs = self.write(
FileWriteAction(path=pre_commit_hook, content=pre_commit_hook_content)
)
if isinstance(write_obs, ErrorObservation):
self.log('error', f'Failed to write pre-commit hook: {write_obs.content}')
return
# Make the pre-commit hook executable
action = CmdRunAction(f'chmod +x {pre_commit_hook}')
obs = self.run_action(action)
if isinstance(obs, CmdOutputObservation) and obs.exit_code != 0:
self.log(
'error', f'Failed to make pre-commit hook executable: {obs.content}'
)
return
self.log('info', 'Git pre-commit hook installed successfully')
def _load_microagents_from_directory(
self, microagents_dir: Path, source_description: str
) -> list[BaseMicroagent]:
"""Load microagents from a directory.
Args:
microagents_dir: Path to the directory containing microagents
source_description: Description of the source for logging purposes
Returns:
A list of loaded microagents
"""
loaded_microagents: list[BaseMicroagent] = []
self.log(
'info',
f'Attempting to list files in {source_description} microagents directory: {microagents_dir}',
)
files = self.list_files(str(microagents_dir))
if not files:
self.log(
'debug',
f'No files found in {source_description} microagents directory: {microagents_dir}',
)
return loaded_microagents
self.log(
'info',
f'Found {len(files)} files in {source_description} microagents directory',
)
zip_path = self.copy_from(str(microagents_dir))
microagent_folder = tempfile.mkdtemp()
try:
with ZipFile(zip_path, 'r') as zip_file:
zip_file.extractall(microagent_folder)
zip_path.unlink()
repo_agents, knowledge_agents = load_microagents_from_dir(microagent_folder)
self.log(
'info',
f'Loaded {len(repo_agents)} repo agents and {len(knowledge_agents)} knowledge agents from {source_description}',
)
loaded_microagents.extend(repo_agents.values())
loaded_microagents.extend(knowledge_agents.values())
except Exception as e:
self.log('error', f'Failed to load agents from {source_description}: {e}')
finally:
shutil.rmtree(microagent_folder)
return loaded_microagents
def _is_gitlab_repository(self, repo_name: str) -> bool:
"""Check if a repository is hosted on GitLab.
Args:
repo_name: Repository name (e.g., "gitlab.com/org/repo" or "org/repo")
Returns:
True if the repository is hosted on GitLab, False otherwise
"""
try:
provider_handler = ProviderHandler(
self.git_provider_tokens or MappingProxyType({})
)
repository = call_async_from_sync(
provider_handler.verify_repo_provider,
GENERAL_TIMEOUT,
repo_name,
)
return repository.git_provider == ProviderType.GITLAB
except Exception:
# If we can't determine the provider, assume it's not GitLab
# This is a safe fallback since we'll just use the default .openhands
return False
def get_microagents_from_org_or_user(
self, selected_repository: str
) -> list[BaseMicroagent]:
"""Load microagents from the organization or user level repository.
For example, if the repository is github.com/acme-co/api, this will check if
github.com/acme-co/.openhands exists. If it does, it will clone it and load
the microagents from the ./microagents/ folder.
For GitLab repositories, it will use openhands-config instead of .openhands
since GitLab doesn't support repository names starting with non-alphanumeric
characters.
Args:
selected_repository: The repository path (e.g., "github.com/acme-co/api")
Returns:
A list of loaded microagents from the org/user level repository
"""
loaded_microagents: list[BaseMicroagent] = []
self.log(
'debug',
f'Starting org-level microagent loading for repository: {selected_repository}',
)
repo_parts = selected_repository.split('/')
if len(repo_parts) < 2:
self.log(
'warning',
f'Repository path has insufficient parts ({len(repo_parts)} < 2), skipping org-level microagents',
)
return loaded_microagents
# Extract the domain and org/user name
org_name = repo_parts[-2]
self.log(
'info',
f'Extracted org/user name: {org_name}',
)
# Determine if this is a GitLab repository
is_gitlab = self._is_gitlab_repository(selected_repository)
self.log(
'debug',
f'Repository type detection - is_gitlab: {is_gitlab}',
)
# For GitLab, use openhands-config (since .openhands is not a valid repo name)
# For other providers, use .openhands
if is_gitlab:
org_openhands_repo = f'{org_name}/openhands-config'
else:
org_openhands_repo = f'{org_name}/.openhands'
self.log(
'info',
f'Checking for org-level microagents at {org_openhands_repo}',
)
# Try to clone the org-level repo
try:
# Create a temporary directory for the org-level repo
org_repo_dir = self.workspace_root / f'org_openhands_{org_name}'
self.log(
'debug',
f'Creating temporary directory for org repo: {org_repo_dir}',
)
# Get authenticated URL and do a shallow clone (--depth 1) for efficiency
try:
remote_url = call_async_from_sync(
self.provider_handler.get_authenticated_git_url,
GENERAL_TIMEOUT,
org_openhands_repo,
)
except AuthenticationError as e:
self.log(
'debug',
f'org-level microagent directory {org_openhands_repo} not found: {str(e)}',
)
raise
except Exception as e:
self.log(
'debug',
f'Failed to get authenticated URL for {org_openhands_repo}: {str(e)}',
)
raise
clone_cmd = (
f'GIT_TERMINAL_PROMPT=0 git clone --depth 1 {remote_url} {org_repo_dir}'
)
self.log(
'info',
'Executing clone command for org-level repo',
)
action = CmdRunAction(command=clone_cmd)
obs = self.run_action(action)
if isinstance(obs, CmdOutputObservation) and obs.exit_code == 0:
self.log(
'info',
f'Successfully cloned org-level microagents from {org_openhands_repo}',
)
# Load microagents from the org-level repo
org_microagents_dir = org_repo_dir / 'microagents'
self.log(
'info',
f'Looking for microagents in directory: {org_microagents_dir}',
)
loaded_microagents = self._load_microagents_from_directory(
org_microagents_dir, 'org-level'
)
self.log(
'info',
f'Loaded {len(loaded_microagents)} microagents from org-level repository {org_openhands_repo}',
)
# Clean up the org repo directory
action = CmdRunAction(f'rm -rf {org_repo_dir}')
self.run_action(action)
else:
clone_error_msg = (
obs.content
if isinstance(obs, CmdOutputObservation)
else 'Unknown error'
)
exit_code = (
obs.exit_code if isinstance(obs, CmdOutputObservation) else 'N/A'
)
self.log(
'info',
f'No org-level microagents found at {org_openhands_repo} (exit_code: {exit_code})',
)
self.log(
'debug',
f'Clone command output: {clone_error_msg}',
)
except AuthenticationError as e:
self.log(
'debug',
f'org-level microagent directory {org_openhands_repo} not found: {str(e)}',
)
except Exception as e:
self.log(
'debug',
f'Error loading org-level microagents from {org_openhands_repo}: {str(e)}',
)
return loaded_microagents
def get_microagents_from_selected_repo(
self, selected_repository: str | None
) -> list[BaseMicroagent]:
"""Load microagents from the selected repository.
If selected_repository is None, load microagents from the current workspace.
This is the main entry point for loading microagents.
This method also checks for user/org level microagents stored in a repository.
For example, if the repository is github.com/acme-co/api, it will also check for
github.com/acme-co/.openhands and load microagents from there if it exists.
For GitLab repositories, it will use openhands-config instead of .openhands
since GitLab doesn't support repository names starting with non-alphanumeric
characters.
"""
loaded_microagents: list[BaseMicroagent] = []
microagents_dir = self.workspace_root / '.openhands' / 'microagents'
repo_root = None
# Check for user/org level microagents if a repository is selected
if selected_repository:
# Load microagents from the org/user level repository
org_microagents = self.get_microagents_from_org_or_user(selected_repository)
loaded_microagents.extend(org_microagents)
# Continue with repository-specific microagents
repo_root = self.workspace_root / selected_repository.split('/')[-1]
microagents_dir = repo_root / '.openhands' / 'microagents'
self.log(
'info',
f'Selected repo: {selected_repository}, loading microagents from {microagents_dir} (inside runtime)',
)
# Legacy Repo Instructions
# Check for legacy .openhands_instructions file
obs = self.read(
FileReadAction(path=str(self.workspace_root / '.openhands_instructions'))
)
if isinstance(obs, ErrorObservation) and repo_root is not None:
# If the instructions file is not found in the workspace root, try to load it from the repo root
self.log(
'debug',
f'.openhands_instructions not present, trying to load from repository {microagents_dir=}',
)
obs = self.read(
FileReadAction(path=str(repo_root / '.openhands_instructions'))
)
if isinstance(obs, FileReadObservation):
self.log('info', 'openhands_instructions microagent loaded.')
loaded_microagents.append(
BaseMicroagent.load(
path='.openhands_instructions',
microagent_dir=None,
file_content=obs.content,
)
)
# Load microagents from directory
repo_microagents = self._load_microagents_from_directory(
microagents_dir, 'repository'
)
loaded_microagents.extend(repo_microagents)
return loaded_microagents
def run_action(self, action: Action) -> Observation:
"""Run an action and return the resulting observation.
If the action is not runnable in any runtime, a NullObservation is returned.
If the action is not supported by the current runtime, an ErrorObservation is returned.
"""
if not action.runnable:
if isinstance(action, AgentThinkAction):
return AgentThinkObservation('Your thought has been logged.')
return NullObservation('')
if (
hasattr(action, 'confirmation_state')
and action.confirmation_state
== ActionConfirmationStatus.AWAITING_CONFIRMATION
):
return NullObservation('')
action_type = action.action # type: ignore[attr-defined]
if action_type not in ACTION_TYPE_TO_CLASS:
return ErrorObservation(f'Action {action_type} does not exist.')
if not hasattr(self, action_type):
return ErrorObservation(
f'Action {action_type} is not supported in the current runtime.'
)
if (
getattr(action, 'confirmation_state', None)
== ActionConfirmationStatus.REJECTED
):
return UserRejectObservation(
'Action has been rejected by the user! Waiting for further user input.'
)
observation = getattr(self, action_type)(action)
return observation
# ====================================================================
# Context manager
# ====================================================================
def __enter__(self) -> 'Runtime':
return self
def __exit__(self, exc_type, exc_value, traceback) -> None:
self.close()
@abstractmethod
async def connect(self) -> None:
pass
@abstractmethod
def get_mcp_config(
self, extra_stdio_servers: list[MCPStdioServerConfig] | None = None
) -> MCPConfig:
pass
# ====================================================================
# Action execution
# ====================================================================
@abstractmethod
def run(self, action: CmdRunAction) -> Observation:
pass
@abstractmethod
def run_ipython(self, action: IPythonRunCellAction) -> Observation:
pass
@abstractmethod
def read(self, action: FileReadAction) -> Observation:
pass
@abstractmethod
def write(self, action: FileWriteAction) -> Observation:
pass
@abstractmethod
def edit(self, action: FileEditAction) -> Observation:
pass
@abstractmethod
def browse(self, action: BrowseURLAction) -> Observation:
pass
@abstractmethod
def browse_interactive(self, action: BrowseInteractiveAction) -> Observation:
pass
@abstractmethod
async def call_tool_mcp(self, action: MCPAction) -> Observation:
pass
# ====================================================================
# File operations
# ====================================================================
@abstractmethod
def copy_to(self, host_src: str, sandbox_dest: str, recursive: bool = False):
raise NotImplementedError('This method is not implemented in the base class.')
@abstractmethod
def list_files(self, path: str | None = None) -> list[str]:
"""List files in the sandbox.
If path is None, list files in the sandbox's initial working directory (e.g., /workspace).
"""
raise NotImplementedError('This method is not implemented in the base class.')
@abstractmethod
def copy_from(self, path: str) -> Path:
"""Zip all files in the sandbox and return a path in the local filesystem."""
raise NotImplementedError('This method is not implemented in the base class.')
# ====================================================================
# Authentication
# ====================================================================
@property
def session_api_key(self) -> str | None:
return None
# ====================================================================
# VSCode
# ====================================================================
@property
def vscode_enabled(self) -> bool:
return self._vscode_enabled
@property
def vscode_url(self) -> str | None:
raise NotImplementedError('This method is not implemented in the base class.')
@property
def web_hosts(self) -> dict[str, int]:
return {}
# ====================================================================
# Git
# ====================================================================