Skip to content

refactor(agent-server): one ServerContext per (re)initialisation - #6702

Merged
VascoSch92 merged 5 commits into
mainfrom
vasco/agent-server-context
Nov 13, 2026
Merged

VascoSch92 merged 5 commits into
mainfrom
vasco/agent-server-context

Conversation

@VascoSch92

@VascoSch92 VascoSch92 commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

HUMAN:

Refactor server context.


AGENT:

Why

Step 5 of #6456 asks for "one ServerContext built per (re)initialisation, reached only through a request dependency and swapped atomically by /api/init, removing the get_default_* fallbacks and store-constructor defaults".

On main the server's config-derived state has several homes that are kept in step by hand: app.state.config, the get_default_config() global that rebuilds config from OH_*, six store singletons in persistence/store.py that keep the cipher and directory of whoever called them first, module-level services in sockets.py built at import, a VSCode service singleton built from whichever config asks first, and four separate app.state.* assignments plus reset_stores() and a patched module global in POST /api/init. That is the structure behind #3844, #3816 and #5921.

The first version of this PR grouped that state in one context but still let handlers fetch it by hand, kept the VSCode singleton, and published the new context before the last fallible step of /api/init (the review thread on init_router.py). This version closes those gaps: dependencies are declared and injected, as #400 proposed, the app owns its services, and /api/init commits only after everything that can fail is done.

Summary

  • One context. ServerContext (frozen) holds config, stores, conversation_registry, conversation_service, bash_event_service and vscode_service. create_app() builds it, the lifespan completes it once the services are started, and POST /api/init installs a whole new one. ServerStores holds the six stores of one config, resolves the cipher and the persistence directories once and creates each store on first use, so building a context touches no file.
  • Routes declare what they need. Every provider in dependencies.py resolves from one Depends(get_server_context), which FastAPI calls once per request or WebSocket, so all the dependencies of a request (the router-level session-key check included) come from the same context. A route asks for Depends(get_settings_store), Depends(get_cipher), Depends(get_conversation_service) and so on; there is a provider per store next to get_stores for code that needs the bundle. Helpers receive the objects instead of a Request. The providers declare their own inputs with Annotated, which makes them required arguments: calling one by hand with only a request is a pyright error rather than a Depends object where the context should be.
  • The app owns its services. The VSCode service is built from the app's own config, kept in the context, started and stopped by the lifespan and carried across /api/init, which only switches its token. The tool-preload service is built by the lifespan that starts it. Code outside a request is handed what it needs: ConversationService, the registries, the MCP OAuth token store, the telemetry sink, the local secret resolver, the git provider lookup, the OpenAI gateway and the launch stores take a store or ServerStores as an argument.
  • /api/init is all-or-nothing. InitService._prepare does every step that can fail and publishes nothing: it derives the root path first, puts the services and the environment changes on one exit stack and the telemetry switch on a second one that only runs on failure. InitService._commit then publishes the result; it is synchronous and made of assignments, so it cannot fail or be interrupted half-way. A failed or cancelled attempt leaves the dormant context, bootstrap key, environment and telemetry sink as they were.
  • Removed, with nothing kept beside the new path:
    • config.get_default_config and its cached config;
    • get_default_conversation_service, get_default_bash_event_service and their singletons;
    • the module-level store getters in persistence (get_settings_store, get_secrets_store, get_provider_connections_store, get_workspaces_store, get_llm_profile_store, get_agent_profile_store), reset_stores and the six module singletons;
    • the module-level services in sockets.py and the fallbacks to them;
    • vscode_service.get_vscode_service(config), tool_preload_service.get_tool_preload_service(config) and their singletons;
    • _secrets_exposure.get_config/get_cipher, openai.router._get_config, and every direct read of app.state.config, .conversation_service, .bash_event_service, .conversation_registry.
  • A test fails if a module other than server_context.py reads that app.state, defines a get_default_* function, or fetches the whole context by hand outside the modules that build or swap it (api.py, init_router.py, the runtime dispatch middleware, the canvas backend manager).
before                                              after
app.state.config / .conversation_service / ...      app.state.server_context  (one frozen object)
get_default_config()        (rebuilt from OH_*)       config ── stores ── registry ── services ── vscode
_settings_store, ... x6     (first caller wins)     route(..., store = Depends(get_settings_store))
_vscode_service             (first config wins)       └─ every provider ── Depends(get_server_context), once per request
/api/init: reset_stores() + 4 assignments           /api/init: _prepare (fallible, undone on failure)
           + patch module global                               then _commit (assignments only)

Merged with main at 10be259. Main's newer code now takes its dependencies the same way: experimental features (#6759) and conversation reactions (#6609) get the settings store injected, pull-request status (#6704) takes the secrets store, the trajectory download (#5766) uses the injected config. Everything raises the domain errors of #6780.

Issue Number

Part of #6456 (step 5, ServerContext half).

How to Test

uv run pytest tests/agent_server/test_server_context.py -q

It has 27 tests: a successful /api/init swaps config, stores, registry and services together; the next request already encrypts with the delivered key in the delivered directory; an init that fails at its last step, one that cannot derive its root path and one that is cancelled each leave the same context object, environment and telemetry sink in place and can be retried; a request resolves its context once; and the guard, with positive and negative cases. The three failure tests fail against the previous InitService.

Real server process (python -m openhands.agent_server, OH_DEFERRED_INIT=1), driven with curl:

 1. dormant state:                         {"state":"dormant","error":null}
 2. conversations while dormant:           HTTP 503
 3. init with a wrong key:                 HTTP 401
 4. init with an unparseable web_url:      HTTP 500
 5. state after the failed init:           {"state":"dormant","error":"ValueError: Invalid IPv6 URL"}
 6. conversations after the failed init:   HTTP 503
 7. retry with the delivered key (wrong):  HTTP 401
 8. retry with the bootstrap key:          {"state":"ready","error":null}
 9. conversations, no key:                 HTTP 401
10. conversations, session key:            HTTP 200
11. save a secret:                         HTTP 200
12. read settings:                         HTTP 200
13. list workspaces:                       HTTP 200
14. list LLM profiles:                     HTTP 200
15. list experimental features:            HTTP 200
16. turn conversation reactions on:        HTTP 200
17. bash command:                          HTTP 200
18. vscode status:                         {"running":false,"enabled":false,"message":"VSCode is disabled in configuration"}
19. second init:                           HTTP 400
files written:
   user/bash/..._BashCommand_...
   user/bash/..._BashOutput_...
   user/persistence/.secrets.lock
   user/persistence/.settings.lock
   user/persistence/profiles/.profiles.lock
   user/persistence/secrets.json
   user/persistence/settings.json

Everything was written under the directories delivered by /api/init, nothing under the ones the process booted with. On the previous head of this PR, steps 7 and 8 were the other way round: after the failed init only the delivered key was accepted.

Other checks, on macOS:

  • tests/agent_server: 3179 passed, 4 failed. The four are canvas-extension backend tests that fail on main too, because the backend reports "unsupported" off Linux. With the platform check patched they pass (16 passed in that file).
  • tests/cross: 746 passed, including test_remote_conversation_live_server.py and the HTTPException guard from refactor(agent-server): map domain errors to HTTP once #6780.
  • OpenAPI: byte-identical to main (10be259) for the default config and for conversation_runtime_selectable=True, 154 paths each.
  • pyright on openhands-agent-server, tests/agent_server and tests/cross: 0 errors. Pre-commit, the docstring check, the OpenAPI quality check and the deprecation check pass.

Video/Screenshots

N/A

Type

  • Bug fix
  • Feature
  • Refactor
  • Breaking change
  • Docs / chore

Notes

  • The removed getters are Python API of openhands-agent-server, which check_sdk_api_breakage.py does not cover. In the OpenHands org I found them used only inside this repo. scripts/build_config_template.py and the verify-agent-server control script now call load_config().
  • Behaviour that changes:
    • The lifespan's bash service is built from the config given to create_app() and closed on shutdown. Before, it came from the environment and was never closed.
    • A failed /api/init leaves nothing behind: the services it started are stopped, the variables from env and the exported session key are restored, the dormant telemetry sink is back and the bootstrap key still works. Before, the services leaked, a retry started a second set, and a failure after the swap left the delivered key in charge of a "dormant" server. A cancelled init returns to dormant instead of staying in initializing.
    • teardown() restores the variables set through env, not only the exported session key.
    • Two apps in one process each get the VSCode service of their own config. Before, the second got the first one's.
    • A declared dependency is resolved before the handler body. Where a route used to look the conversation or bash service up late, "service not running" is now answered first: the event, bash and session WebSockets close with 1013 before the handshake, as the dormant gate already does, and the Docker runtime and credential-binding routes return 503 before doing any work. On a started server this cannot happen. For the same reason a request that fails validation can leave an empty store directory behind, because three stores create their directory when built.
    • CanvasExtensionBackendManager(secrets_store=...) takes a callable, because the manager outlives /api/init and has to read the current context's store.
  • Left as process state on purpose: the telemetry sink (its switch during /api/init is undone on failure, but it is still one sink per process), the skills and plugin catalog caches, and the /ready flag.
  • Not changed here: the lifespan and /api/init still start the services through two separate code paths.
  • Draft fix(sdk): bind the cipher to LLMProfileStore so no profile load can drop it #6612 changes get_llm_profile_store, which no longer exists in persistence here, so whichever lands second needs a rebase in persistence/store.py, launch.py and the profile routers.
  • The LLM half of step 5 was refactor(sdk): keep LLM usage and telemetry in sessions keyed by role #6690, now merged.

🐳 Agent Server images for this PR — GHCR package, pull/run commands, and all pushed tags (click to expand)

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant Architectures Base Image Docs / Tags
java amd64, arm64 eclipse-temurin:17-jdk Link
python-slim amd64, arm64 python-node-runtime Link
python-minimal amd64, arm64 python-node-runtime Link
python amd64, arm64 python-node-runtime Link
golang amd64, arm64 golang:1.21-bookworm Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:164b62a-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-164b62a-python \
  ghcr.io/openhands/agent-server:164b62a-python

All tags pushed for this build

ghcr.io/openhands/agent-server:164b62a-golang-amd64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-golang-amd64
ghcr.io/openhands/agent-server:vasco-agent-server-context-golang-amd64
ghcr.io/openhands/agent-server:164b62a-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:164b62a-golang-arm64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-golang-arm64
ghcr.io/openhands/agent-server:vasco-agent-server-context-golang-arm64
ghcr.io/openhands/agent-server:164b62a-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:164b62a-java-amd64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-java-amd64
ghcr.io/openhands/agent-server:vasco-agent-server-context-java-amd64
ghcr.io/openhands/agent-server:164b62a-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:164b62a-java-arm64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-java-arm64
ghcr.io/openhands/agent-server:vasco-agent-server-context-java-arm64
ghcr.io/openhands/agent-server:164b62a-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:164b62a-python-amd64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-amd64
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-amd64
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-amd64
ghcr.io/openhands/agent-server:164b62a-python-arm64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-arm64
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-arm64
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-arm64
ghcr.io/openhands/agent-server:164b62a-python-minimal-amd64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-minimal-amd64
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-minimal-amd64
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-minimal-amd64
ghcr.io/openhands/agent-server:164b62a-python-minimal-arm64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-minimal-arm64
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-minimal-arm64
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-minimal-arm64
ghcr.io/openhands/agent-server:164b62a-python-slim-amd64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-slim-amd64
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-slim-amd64
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-slim-amd64
ghcr.io/openhands/agent-server:164b62a-python-slim-arm64
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-slim-arm64
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-slim-arm64
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-slim-arm64
ghcr.io/openhands/agent-server:164b62a-golang
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-golang
ghcr.io/openhands/agent-server:vasco-agent-server-context-golang
ghcr.io/openhands/agent-server:164b62a-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:164b62a-java
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-java
ghcr.io/openhands/agent-server:vasco-agent-server-context-java
ghcr.io/openhands/agent-server:164b62a-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:164b62a-python-minimal
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-minimal
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-minimal
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-minimal
ghcr.io/openhands/agent-server:164b62a-python-slim
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python-slim
ghcr.io/openhands/agent-server:vasco-agent-server-context-python-slim
ghcr.io/openhands/agent-server:164b62a-python-node-runtime-slim
ghcr.io/openhands/agent-server:164b62a-python
ghcr.io/openhands/agent-server:164b62a64eb1c758777cb90cd8fab95678210b89-python
ghcr.io/openhands/agent-server:vasco-agent-server-context-python
ghcr.io/openhands/agent-server:164b62a-python-node-runtime

About Multi-Architecture Support

  • Each variant tag (e.g., 164b62a-python) is a multi-arch manifest supporting both amd64 and arm64
  • Docker automatically pulls the correct architecture for your platform
  • Individual architecture tags (e.g., 164b62a-python-amd64) are also available if needed

A server's config, its six persistent stores, its conversation registry and
its conversation and bash services now live together in one frozen
ServerContext. It is built when the app is created, completed by the lifespan
once the services are started, and rebuilt whole by POST /api/init, which
installs it with a single assignment after everything is up. A failed init
stops what it started and leaves the dormant context untouched.

Request handlers reach the context through the dependencies in
dependencies.py (get_config, get_cipher, get_stores, get_conversation_registry,
get_conversation_service, get_server_bash_event_service). Code that runs
outside a request is handed the store or service it needs: ConversationService,
the conversation registries, the MCP OAuth token store, the telemetry sink, the
local secret resolver, the git provider lookup, the OpenAI gateway and the
launch stores all take them as arguments.

Removed, with no replacement kept beside the new path:
- config.get_default_config and the cached default config
- conversation_service.get_default_conversation_service and its singleton
- bash_service.get_default_bash_event_service and its singleton
- persistence.get_settings_store, get_secrets_store,
  get_provider_connections_store, get_workspaces_store, get_llm_profile_store,
  get_agent_profile_store, reset_stores and the six module singletons
- the module-level conversation_service / bash_event_service in sockets.py and
  the fallbacks to them
- _secrets_exposure.get_config / get_cipher, openai.router._get_config and
  every direct read of app.state.config, .conversation_service,
  .bash_event_service and .conversation_registry

ServerStores resolves the cipher and the persistence directories once, when it
is built, and creates each store on first use, so building a context touches
no file. The lifespan's bash service is now built from the config given to
create_app (it used to come from the environment) and is closed on shutdown.

A test in tests/agent_server/test_server_context.py fails if a module other
than server_context.py reads config-derived app.state, or defines a
get_default_* function.

The REST surface is unchanged: the OpenAPI document is byte-identical before
and after.

Part of #6456 (step 5, ServerContext half).
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

@datadog-official

This comment has been minimized.

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Coverage

Coverage Report •
FileStmtsMissCoverMissing
openhands-agent-server/openhands/agent_server
   _secrets_exposure.py60297%70, 108
   acp_router.py94496%109–111, 139
   agent_profiles_router.py2261394%104, 192, 196, 200, 219, 222, 317, 320, 323–324, 510, 544–545
   api.py4513492%146, 200–201, 210–211, 213, 216–217, 224–225, 239–240, 257, 263, 266–267, 364, 378, 384, 453, 458, 471–473, 506, 535, 541, 545, 566–567, 853, 856, 858, 864
   bash_service.py2903588%136–138, 275, 295–298, 309, 343–344, 392, 397–398, 423–428, 494–495, 499–504, 530–531, 567–568, 572, 605–606
   canvas_extensions_router.py186796%221, 353, 361–364, 366
   config.py165199%598
   conversation_router.py3191695%121–122, 125–126, 338, 472, 521, 579, 752, 814–816, 860, 897–898, 929
   conversation_service.py128810092%203–204, 286, 307, 496–497, 666, 673–674, 775, 829–830, 834, 839, 889, 941–942, 949, 982–983, 999, 1031, 1035, 1048, 1068, 1089–1090, 1099, 1168, 1178, 1203, 1209–1210, 1214–1215, 1223, 1250, 1256, 1350, 1356, 1361, 1367, 1375–1376, 1385–1388, 1397, 1410, 1428, 1465, 1469–1473, 1496, 1545, 1558, 1566, 1824, 1902, 2031, 2034, 2041–2043, 2046–2047, 2053, 2063, 2067, 2096, 2105, 2164–2166, 2197, 2328, 2331, 2358, 2368, 2373–2376, 2390, 2401, 2413–2414, 2446, 2545, 2610, 2668, 2683–2684, 3088, 3141, 3144
   credential_binding.py84989%50, 65–66, 69–70, 89–90, 136, 149
   dependencies.py91298%151, 198
   event_router.py135795%322, 332, 335–336, 387–388, 428
   file_router.py4877485%131–133, 159–161, 229–231, 344, 347–348, 355–356, 394, 396–398, 447, 491–494, 500–502, 508–510, 522–523, 560, 628–630, 635, 639–641, 683–684, 693, 700, 721–723, 771–773, 797–798, 802–803, 811, 813–818, 821–823, 898–899, 903–904, 1108–1114
   git_provider_service.py1941294%86, 121, 147, 273–274, 303–306, 378, 395, 399
   git_router.py1231191%124–126, 137–139, 166, 208, 268, 280, 283
   init_router.py181498%220, 222, 226, 228
   launch.py124497%161, 164–165, 190
   local_secret_resolver.py47296%50, 74
   mcp_oauth_store.py2324780%71, 84, 98, 154, 162, 176, 189, 299, 315–316, 319–322, 329, 332, 343, 348, 358–361, 366–370, 391, 397, 413–419, 424, 429, 439–442, 447–451
   mcp_router.py3933791%197, 200, 206, 211, 393, 428–430, 433–434, 437, 468–471, 474–475, 479–480, 524–525, 657–659, 887, 918–919, 926, 954, 959, 967, 991, 993–994, 1004–1006
   meta_profiles_router.py104199%168
   profiles_router.py195697%539–544
   provider_connections_router.py120993%197–198, 216, 220, 241–242, 260, 266–267
   runtime_router.py55493%47, 63–64, 66
   server_details_router.py82298%34–35
   session_socket.py3184885%154, 158–159, 164, 166–169, 182–184, 371, 400, 405–406, 409, 419, 421–422, 425, 445–448, 451, 467, 470, 474, 478, 484, 500, 521, 559–560, 571, 583, 587–589, 594–599, 602–603, 606
   settings_router.py204598%620, 622–623, 663, 668
   sockets.py2572291%163, 166, 169, 249–250, 254, 266–267, 270, 393–396, 401–402, 407–409, 481, 516, 543, 561
   tool_preload_service.py26581%25, 41–43, 51
   vscode_service.py1431590%80–83, 96–97, 100–102, 203, 212, 261, 266, 295–296
   workspaces_router.py1172380%70–72, 115–116, 143–148, 186–191, 215–220
openhands-agent-server/openhands/agent_server/canvas_extensions
   backend.py6798188%60–61, 197, 201–203, 218, 221, 294–295, 310, 332, 360–362, 365–367, 370–371, 375, 382, 388, 393–395, 418, 424, 428, 432, 441, 444, 451, 475–476, 479, 508–510, 537–538, 578–583, 629–630, 679, 703–704, 733, 736–737, 752–753, 779, 786, 794, 807, 811, 815, 822–823, 866, 904–905, 950, 964, 980, 983–984, 1000–1002, 1004, 1010–1011, 1023, 1051
   bridge.py2872691%124, 140, 155, 171–173, 238–239, 246, 249, 256, 265, 268, 271, 315, 320, 341, 354, 357, 380, 396, 451, 502–504, 509
openhands-agent-server/openhands/agent_server/docker_runtime
   hybrid.py102991%41–43, 46, 105–106, 152, 166–167
   registry.py4187383%95, 100, 103, 116–118, 121, 126, 161, 252, 290, 310–312, 314–315, 318–321, 332, 358–360, 392, 402–406, 412, 416–417, 426, 486, 495–497, 501–505, 519, 554, 558–561, 567, 590, 624–625, 629, 677, 772, 779, 787–789, 792–800, 809–812
   routers.py2786975%79, 87, 94–96, 139–141, 158–159, 161, 188, 196–197, 242, 265, 268–271, 274–278, 311–312, 346, 358, 372, 376–378, 389–391, 404, 407, 417–418, 465, 479–480, 524–526, 550, 552–564, 567–569, 575–578, 590, 610
openhands-agent-server/openhands/agent_server/openai
   router.py69297%110, 116
   service.py3385584%105, 115–118, 126, 130–140, 142–146, 161, 187–192, 223, 232, 234, 257, 267–268, 368, 375, 382, 401–404, 501–502, 585–586, 592, 599–600, 674–675, 699, 716, 725, 790
openhands-agent-server/openhands/agent_server/persistence
   store.py4586785%50–51, 101, 105, 109, 113, 117, 123, 146–147, 169, 172–175, 177–178, 183, 220, 222–226, 228–232, 237–242, 265, 268–269, 384–385, 390, 392–393, 520, 553–554, 559, 561–562, 570, 647–648, 727, 729, 748, 752, 770–771, 777, 845–846, 850–852, 871, 1030–1031
openhands-agent-server/openhands/agent_server/telemetry
   service.py110893%82–83, 229, 232–234, 248–249
TOTAL555172108662% 

@smolpaws smolpaws left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, I’m Codex (posting as @smolpaws), reviewing this PR at Engel’s request.

Reviewed 5b04a3a4c. One material gap remains in the stated transactional-initialization outcome: root-path parsing can fail after the new context and services have been committed. The inline comment includes a real HTTP reproducer and the resulting authentication/cleanup failure. This sequence also fails on the base revision; I’m flagging it because preserving the dormant context and unwinding services on failed init are explicit outcomes of this refactor.

Validation: 89 focused context/init/socket/store tests and seven real HTTP/WebSocket tests passed; current-head CI is green. I also independently verified the intended bash-directory fix in separate server processes: base writes to the environment-selected directory, while this head correctly uses the explicit Config directory.

Leaving a COMMENT pending the rollback fix.

bash_event_service=bash_svc,
),
)
self._started = started.pop_all()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Finish fallible preparation before committing the new context

_get_root_path(new_config) can still raise after install_server_context() and started.pop_all(). I reproduced this through real HTTP against this head: boot dormant with bootstrap key explicit-key, then POST /api/init using that key with {"secret_key":"new-key","web_url":"http://["}. It returns 500 (ValueError: Invalid IPv6 URL) and reports dormant, but a corrected retry using explicit-key returns 401; only new-key works. The failed attempt also retains its conversation renewal task, and retrying starts a second one.

This leaves the PR’s failed-init rollback guarantee incomplete. Calculate/validate the root path before installing the context and transferring the exit stack, so this failure unwinds and the bootstrap key remains valid for retry.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codex follow-up (posting as @smolpaws): verified fixed by 4afd12d on current head 164b62a. I reran the original real-server HTTP reproduction: malformed web_url returns 500 and leaves the server dormant; the bootstrap-key retry now succeeds, the delivered key is rejected before successful initialization, and renewal tasks are 0 after failure / 1 after retry (previously 1 / 2). Root-path preparation now happens before side effects, and the cleanup stack remains owned until preparation succeeds. Resolving this finding.

…ices

The VSCode service was a module singleton built from whichever config
asked first. A second app in the same process got the first app's
editor: created with enable_vscode=False it still reported
"enabled": true, and a different vscode_port was ignored.

build_server_context() now builds the service of its own config and
keeps it in ServerContext.vscode_service. The lifespan starts and stops
it, POST /api/init carries it into the next context and only switches
its token, and routes receive it through Depends(get_vscode_service).
The tool-preload service is built by the lifespan that starts it.
get_vscode_service(config), get_tool_preload_service(config) and both
module singletons are gone.

This also fixes GET /api/conversations/{id}/vscode/url on a server with
VSCode disabled. The runtime router calls the get_vscode_url handler as
a plain function, so its config parameter was the Depends default and
the request failed with a 500 instead of the 503 the plain route gives.
A failed /api/init reported "dormant" while keeping parts of the attempt.
With a web_url that cannot be parsed, the root path was derived after the
new context was installed: the request failed with a 500, but the
delivered key already guarded /api/init (a retry with the bootstrap key
got 401) and the conversation service kept running. Any failed attempt
also left the variables from "env" in the process and the delivered
telemetry sink in place of the dormant one, and a cancelled attempt left
the server in "initializing" for good.

InitService.initialize now has two phases:

- _prepare does every step that can fail and publishes nothing. The
  root path is derived first. The services and the environment go on one
  exit stack, the telemetry switch on a second one that only runs when
  the attempt fails, so a failure or a cancellation undoes all of it.
- _commit publishes the result. It is synchronous and made of
  assignments, so it cannot fail or be interrupted half-way.

teardown() unwinds the same stack, so it now also restores the variables
set through "env", not only the exported session key.
The providers in dependencies.py took a Request and were called by hand
inside handler bodies and helpers (get_stores(request) in 48 places,
get_cipher(request) in 16, get_config(request) in 15), so what a route
depended on was not in its signature and every call read app.state
again.

Every provider now resolves from Depends(get_server_context), which
FastAPI calls once per request or WebSocket. A route names what it needs
(Depends(get_settings_store), Depends(get_cipher), ...), helpers receive
the objects instead of the request, and all the dependencies of one
request, including the router-level session-key check, come from the
same ServerContext. There is one provider per store next to get_stores
for code that needs the whole bundle.

The providers declare their own inputs with Annotated, which makes them
required arguments: calling one by hand with only a request is now a
type error instead of leaving a Depends object where the context should
be. The guard test also rejects fetching the whole context by hand
outside the modules that build or swap it.

No route, parameter, status code or response changes; the OpenAPI schema
is byte-identical. A declared dependency is resolved before the handler
body, so where a route used to look the conversation or bash service up
late, "service not running" is now answered first: the event, bash and
session WebSockets close with 1013 before the handshake, like the
dormant gate already does, and the docker runtime and credential-binding
routes return 503 before doing any work.
Fifty files conflicted, most of them with #6780 (domain errors), which
rewrote the raises in every router this branch rewrote the lookups of.
Each conflict keeps main's errors, responses and new behaviour and this
branch's injected dependencies.

Code main added since the branch point that used lookups this branch
removed now takes its dependencies like the rest:

- experimental features (#6759): the routes take the settings store
  through Depends(get_settings_store).
- conversation reactions (#6609): require_reactions_enabled takes a
  settings store; the route injects it and the Docker proxy passes the
  registry's.
- pull request status (#6704): get_provider_pull_request takes the
  secrets store.
- trajectory download (#5766): uses the injected config.
- DockerConversationRegistry and the OpenAI gateway read experimental
  features from their own ServerStores.

Code that exists only on this branch raises domain errors too
(dependencies.py, init_router.py, vscode_router.py); a WebSocket that
finds no service still closes with 1013.

Tests main added for these features build their stores per test instead
of reading a process-wide one.

@smolpaws smolpaws left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, I’m Codex (posting as @smolpaws), reviewing this PR at Engel’s request.

Re-reviewed at 164b62a64eb1c758777cb90cd8fab95678210b89. Approve. The revised architecture addresses my concerns.

Compared with the earlier version and the approach in #400, this now has the right ownership and dependency structure:

  • Routes declare narrow dependencies through FastAPI; providers share one cached get_server_context result per request. Helpers receive the objects they use. ServerContext is the app’s resource bundle, rather than a service locator fetched throughout handler bodies.
  • The app owns its VSCode service and tool-preload lifecycle. Independent HTTP checks against separately configured apps confirmed that enabling VSCode in one app no longer makes a disabled app report it enabled.
  • Deferred initialization prepares the replacement before publishing it, retaining cleanup ownership until preparation succeeds. The original root-path failure no longer changes the bootstrap credential or leaks a renewal task.

I reran the original real uvicorn/HTTP reproducer: malformed web_url returns 500 with the server still dormant; retry with the bootstrap key succeeds; renewal tasks are zero after failure and one after retry, versus one and two before the fix. I also checked the new dependency graph through authentication, WebSockets, Docker/hybrid routing, profiles, settings, and workspaces. No material finding remains in the reviewed changes.

Validation on this head: 94 focused context/init/store tests, 132 focused transport/runtime tests, and 380 HTTP/authentication tests passed. Current code/test CI checks pass. Telemetry remains process-wide as documented; this approval does not claim complete isolation of all process globals.

The remaining failed CI check is the unresolved-thread gate for my original finding. I posted the verified-fix reply, but GitHub denies this account permission to resolve the thread. A maintainer or the author can resolve it; the finding is addressed. Nothing remains to fix for that review comment.

@VascoSch92
VascoSch92 merged commit 00bce7f into main Nov 13, 2026
55 of 57 checks passed
@VascoSch92
VascoSch92 deleted the vasco/agent-server-context branch November 13, 2026 14:09
arpitrusia added a commit to arpitrusia/software-agent-sdk that referenced this pull request Nov 13, 2026
Upstream moved 9 commits since the last sync (notably the ServerContext
refactor OpenHands#6702). Two content conflicts, resolved surgically:

- api.py: import union (our ContentSearchService + upstream server_context);
  our startup sync block retained verbatim after upstream's reordered
  lifespan; the router mount condition and construction guard unchanged.
- conversation_router.py: our search imports + router kept; upstream moved
  get_llm_profile_store into the shared persistence import block so the
  duplicate HEAD-side import was dropped; upstream's typed NotFound() and
  dropped request:Request were re-added where our search-prune block
  needs them.

Diff vs origin/main contains only the feature lines. py_compile clean.

Co-authored-by: openhands <openhands@all-hands.dev>
enyst pushed a commit that referenced this pull request Nov 13, 2026
Main replaced the process-wide stores with ServerStores. Projects follows:
ServerStores.projects holds projects.json, the projects routes take their
stores through Depends, the service and the coordinator relay read the
service's stores, ensure_project_profile and feature_enabled_now take the
store they read, and the send route resolves the conversation service only
for a message another conversation sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
arpitrusia added a commit to arpitrusia/software-agent-sdk that referenced this pull request Nov 13, 2026
The ServerContext refactor (OpenHands#6702) moved config into ServerContext and
stopped setting api.state.config. My re-sync collision resolution kept
one stale read of it in the content-search startup block, crashing every
non-deferred startup whenever OH_CONTENT_SEARCH_ENABLED was on. The
search suite never entered the app lifespan, so 61 green tests missed
it; a real deploy exposed it within seconds.

Adds a lifespan-entering regression test that fails against the bug and
passes with the fix (verified both directions).

Co-authored-by: openhands <openhands@all-hands.dev>
enyst pushed a commit that referenced this pull request Nov 14, 2026
ConversationService takes one ServerStores since #6702; the two tests
that restart a service on an older meta.json still passed secrets_store.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY
@enyst enyst mentioned this pull request Nov 14, 2026
1 of 5 tasks
vnktadithya added a commit to vnktadithya/OpenHands-software-agent-sdk that referenced this pull request Nov 15, 2026
Adapts the branch to two upstream changes in the same area:

- OpenHands#6780 maps domain errors to HTTP in one place. The metadata lock timeout
  is now a LockTimeout, so ERROR_STATUS answers 503; the branch's own
  exception handler in api.py is gone, and routes declare the 503 with
  error_responses(). Canvas install re-raises LockTimeout before its
  OSError clause, since a LockTimeout is also an OSError.
- OpenHands#5756 adds strict loading. strict stays on list_installed, load_installed,
  sync and load_from_dir. InstallationMetadata.open() drops it: a session
  already refuses metadata it cannot load, so strict had no effect there.

OpenHands#6702 removed reset_stores(); the responsiveness test no longer needs it,
as create_app() builds its own stores.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants