refactor: group agent code by adapter

[Nikhil (shadowfax92)]

Summary

• Groups Claude, Codex, Hermes, and OpenClaw adapter-owned code under apps/server/src/lib/agents/<adapter>/.
• Keeps shared runtime primitives in apps/server/src/lib/agents/runtime/ and leaves ACPX/store/container orchestration common.
• Moves Hermes provider/path helpers and OpenClaw domain modules out of api/services/* into adapter folders behind barrels.

Design

This is a compatibility-preserving file organization refactor. Adapter-specific runtimes, prepare functions, provider/path helpers, and OpenClaw domain services now live behind lib/agents/{claude,codex,hermes,openclaw}. lib/agents/runtime now exports only common runtime contracts, base classes, errors, registry, and shared types.

Test plan

• bun --env-file=apps/server/.env.development test apps/server/tests/lib/agents/claude/runtime.test.ts apps/server/tests/lib/agents/codex/runtime.test.ts apps/server/tests/lib/agents/acpx-agent-adapter.test.ts apps/server/tests/main.test.ts
• bun --env-file=apps/server/.env.development test apps/server/tests/lib/agents/hermes/runtime.test.ts apps/server/tests/lib/agents/hermes/paths.test.ts apps/server/tests/lib/agents/acpx-runtime.test.ts apps/server/tests/api/services/agents/agent-harness-service.test.ts apps/server/tests/main.test.ts
• bun --env-file=apps/server/.env.development test apps/server/tests/lib/agents/openclaw apps/server/tests/api/routes/openclaw.test.ts apps/server/tests/api/routes/agents.test.ts apps/server/tests/api/services/agents/agent-harness-service.test.ts apps/server/tests/main.test.ts
• bun --env-file=apps/server/.env.development test apps/server/tests/lib/agents/runtime apps/server/tests/lib/agents/acpx-runtime.test.ts apps/server/tests/lib/agents/acpx-agent-adapter.test.ts apps/server/tests/api/routes/agents.test.ts apps/server/tests/main.test.ts
• bun run --filter @browseros/server typecheck
• bun run --filter @browseros/server test:all
• stale import rg checks for deleted runtime/service paths

[Nikhil (shadowfax92)]

Claude (@claude) review

[Nikhil (shadowfax92)]

Greptile (@greptileai) review

[claude]

Claude finished Nikhil (@shadowfax92)'s task in 2m 2s —— View job

---

Code Review

• Gather context and understand the request
• Review diff and changed files
• Analyze barrel exports and module structure
• Check for correctness issues
• Post review findings

---

Overall this is a well-executed structural refactor. The layering goal is clear (adapter-specific code behind per-adapter barrels, shared runtime contracts kept common), and the execution is consistent across all four adapters. A few notes below.

What's working well

Structural correctness. Old api/services/openclaw/ and api/services/hermes/ directories are fully deleted. No stale imports remain in src/ (verified with rg). The runtime/index.ts is correctly stripped to shared-only contracts (ContainerAgentRuntime, errors, base classes, registry, types) — adapter-specific symbols now belong exclusively to their adapter barrels.

Import direction. Moving configureOpenClawService/getOpenClawService from api/services/openclaw/ into lib/agents/openclaw/ is the right call — these are domain-level lifecycle operations, not API-layer logic. main.ts now correctly imports them from lib/agents/openclaw rather than reaching into the API services layer.

Consistency across adapters. All four adapters (claude, codex, hermes, openclaw) follow the same barrel pattern. The new hermes/paths.test.ts adds meaningful test coverage for path helpers and provider mapping that had no dedicated tests before.

acpx-agent-adapter.ts simplification (acpx-agent-adapter.ts:8-11). The prepare-function dispatch is now a clean 4-line per-adapter import, removing the previous awkward cross-adapter bundle from runtime.

---

Minor observations

tests/lib/agents/hermes/paths.test.ts tests more than paths. The file tests getHermesProviderMapping (from provider-map.ts) alongside the path helpers. The name paths.test.ts is slightly misleading — adapter.test.ts or helpers.test.ts would be more accurate. Not a blocker, just a naming note for future discoverability.

openclaw/index.ts is a flat 111-line re-export of the entire domain. This is intentional and acceptable as the adapter boundary, but it means new files added to openclaw/ won't automatically be exported — maintainers need to consciously update index.ts. Worth a brief comment or doc note in the barrel, e.g.:

// Re-export all public symbols from the openclaw adapter.
// When adding a new module under openclaw/, also update this barrel.

history-mapper.ts:28 cross-module import. lib/agents/openclaw/history-mapper.ts imports unwrapBrowserosAcpUserMessage from ../../agents/acpx-runtime. This means the openclaw adapter has a compile-time dependency on acpx-runtime.ts. It's not a circular dep (verified: acpx-runtime.ts → hermes → hermes/runtime.ts with no back-edge to history-mapper), but it's worth watching — if acpx-runtime grows to import from openclaw, a cycle forms. The import is justified here (message unwrapping logic lives in acpx-runtime to stay co-located with the prompt builder), just flagging as a watchpoint.

container-runtime.ts net -4 lines (5 added, 9 deleted) beyond the path updates. The substantive change appears to be import path shortening now that the file lives inside lib/agents/openclaw/ (no more ../../lib/agents/ hops). Confirmed correct.

---

No issues found

The compatibility-preserving claim holds: all consumers updated, tests pass per the PR's test plan, and rg checks confirm no orphaned imports. This is ready to merge from a correctness standpoint.

[github-actions]

✅ Tests passed — 1222/1226

Suite	Passed	Failed	Skipped
✅ agent	76/76	0	0
✅ build	9/9	0	0
✅ eval	93/93	0	0
✅ server-agent	261/261	0	0
✅ server-api	86/86	0	0
✅ server-browser	4/4	0	0
✅ server-integration	9/10	0	1
✅ server-lib	362/362	0	0
✅ server-root	60/63	0	3
✅ server-skills	31/31	0	0
✅ server-tools	231/231	0	0

View workflow run

[greptile-apps]

Greptile Summary

This is a compatibility-preserving file organization refactor that groups adapter-owned code under lib/agents/{claude,codex,hermes,openclaw}/ barrel folders, moves Hermes provider/path helpers and OpenClaw domain modules out of api/services/*, and trims lib/agents/runtime/index.ts to only shared runtime contracts and base classes.

• Barrel files added — claude/index.ts, codex/index.ts, hermes/index.ts, and openclaw/index.ts each re-export their adapter's complete surface so callers use a single import path per adapter.
• Import sites updated — all 50 changed files (source + tests) have been migrated from old api/services/openclaw/… and lib/agents/runtime adapter paths to the new barrel imports; rg checks in the test plan confirm no stale paths remain.
• runtime/index.ts slimmed — removed ClaudeRuntime, CodexRuntime, HermesContainerRuntime, and their helpers from the shared runtime barrel, keeping only AgentRuntime, ContainerAgentRuntime, HostProcessAgentRuntime, AgentRuntimeRegistry, shared errors, and common types.

Confidence Score: 5/5

All import paths were correctly updated across source and test files; no stale references remain to the old api/services/openclaw or lib/agents/runtime adapter paths.

The change is purely a file reorganization with no logic changes. Every call site was migrated to the new barrel imports, the runtime/index.ts was correctly trimmed to shared-only exports, all test files were updated and run as part of the test plan, and a grep sweep confirmed no leftover references to deleted paths.

No files require special attention. The openclaw/index.ts barrel is large (111 lines, 13 re-export groups) but accurately reflects the breadth of the OpenClaw domain surface.

Important Files Changed

Filename	Overview
packages/browseros-agent/apps/server/src/lib/agents/openclaw/index.ts	New barrel file re-exporting all 13 OpenClaw sub-modules; includes prepareOpenClawContext from the pre-existing prepare.ts, all error types, env helpers, CLI/HTTP clients, produced-files store, and runtime-state utilities.
packages/browseros-agent/apps/server/src/lib/agents/hermes/index.ts	New barrel for the Hermes adapter, correctly re-exporting paths, provider-map, and runtime (configure/get/prepare functions plus runtime class and config type).
packages/browseros-agent/apps/server/src/lib/agents/claude/index.ts	New barrel for the Claude adapter; re-exports ClaudeRuntime, config types, configure/get functions, and prepareClaudeCodeContext from the colocated runtime.ts.
packages/browseros-agent/apps/server/src/lib/agents/codex/index.ts	New barrel for the Codex adapter; mirrors the Claude barrel pattern, re-exporting CodexRuntime plus configure/get/prepare functions.
packages/browseros-agent/apps/server/src/lib/agents/runtime/index.ts	Correctly narrowed to only shared runtime contracts: AgentRuntime, ContainerAgentRuntime, HostProcessAgentRuntime, registry, errors, and common types — all adapter-specific exports removed.
packages/browseros-agent/apps/server/src/lib/agents/acpx-agent-adapter.ts	Correctly updated to import each adapter's prepare function from its own barrel (./claude, ./codex, ./hermes, ./openclaw) instead of the old mixed runtime/openclaw paths.
packages/browseros-agent/apps/server/src/main.ts	Startup wiring updated to import configureClaudeRuntime/configureCodexRuntime from per-adapter barrels and OpenClaw service from lib/agents/openclaw instead of the old api/services path.
packages/browseros-agent/apps/server/src/api/services/agents/agent-harness-service.ts	Import consolidation: Hermes provider helpers and OpenClaw file-preview/produced-files types now sourced from their adapter barrels instead of the deleted api/services sub-paths.
packages/browseros-agent/apps/server/src/lib/agents/hermes/runtime.ts	Full HermesContainerRuntime implementation moved here from runtime/; internal imports use the new paths module and runtime/ shared base classes; configureHermesRuntime and getHermesRuntime factory functions included.
packages/browseros-agent/apps/server/tests/main.test.ts	Test wiring correctly updated to import and spy on per-adapter barrel modules (claude, codex, hermes) and openclaw service module instead of the old unified runtime import.
packages/browseros-agent/apps/server/tests/lib/agents/hermes/paths.test.ts	New test file covering getHermesHostStateDir, getHermesHarnessHostDir, getHermesAgentHomeHostDir, writeHermesPerAgentProvider (including the custom-provider base_url guard), and getHermesProviderMapping.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[main.ts] --> B[lib/agents/claude]
    A --> C[lib/agents/codex]
    A --> D[lib/agents/hermes]
    A --> E[lib/agents/openclaw]

    F[acpx-agent-adapter.ts] --> B
    F --> C
    F --> D
    F --> E

    G[acpx-runtime.ts] --> D

    H[agent-harness-service.ts] --> D
    H --> E

    I[api/routes/agents.ts] --> E
    J[api/routes/openclaw.ts] --> E

    B --> B1[claude/runtime.ts]
    C --> C1[codex/runtime.ts]
    D --> D1[hermes/runtime.ts]
    D --> D2[hermes/paths.ts]
    D --> D3[hermes/provider-map.ts]
    E --> E1[openclaw/openclaw-service.ts]
    E --> E2[openclaw/container-runtime-factory.ts]
    E --> E3[openclaw/prepare.ts]
    E --> E4[...10 more modules]

    K[lib/agents/runtime] --> L[Shared Primitives Only]
    L --> L1[AgentRuntime interface]
    L --> L2[ContainerAgentRuntime]
    L --> L3[HostProcessAgentRuntime]
    L --> L4[AgentRuntimeRegistry]
    L --> L5[Errors + Types]

    B1 --> K
    C1 --> K
    D1 --> K

Loading

_{Reviews (1): Last reviewed commit: "fix(openclaw): export produced file row ..." | Re-trigger Greptile}