clawwork-ai / clawwork-ai/ClawWork
Plan ClawWork Next RuntimeAdapter path for ACP multi-agent support
- Dominant language
- TypeScript
- Stars
- 532
- Forks
- 75
- Avg merge
- 5h 31m
- Merged PRs (30d)
- 1
Description
## Context
ClawWork currently talks directly to OpenClaw Gateway and models a Task around OpenClaw session semantics. The next architecture goal is to support multiple agent runtimes through a task-first workspace model, including ACP-capable runtimes, without forcing every runtime to pretend it is OpenClaw Gateway.
This issue captures the preferred path: **do not make an OpenClaw Gateway compatibility facade the primary architecture**. Instead, evolve ClawWork Next around `RuntimeAdapter` + `Execution` + event normalization, then add ACP as one runtime adapter.
## Problem
A compatibility facade can make ClawWork connect to another backend quickly, but it preserves the wrong abstraction:
```text
ClawWork -> fake OpenClaw Gateway -> other runtime
```
That is useful for a short proof, but it keeps ClawWork product logic tied to OpenClaw Gateway concepts like `sessionKey`, `chat.send`, `agent` events, Gateway agent catalogs, and Gateway-specific session lifecycle.
For ClawWork Next, the better question is not "how do we emulate OpenClaw Gateway?" but:
> How does a Task map to one or more runtime executions, regardless of whether the runtime is OpenClaw, ACP, Codex, Claude Code, Hermes, or a managed agent backend?
## Direction
Introduce a runtime-agnostic execution boundary:
```text
Product Layer
Task / Message / Artifact / Team
Execution Control Plane
Execution / Placement / ExecutionProfile
Event normalization / Recovery / Approval / Observability
Runtime Adapter Layer
OpenClawGatewayAdapter
ACPAdapter
CodexAdapter
ClaudeCodeAdapter
HermesAdapter
Runtime Engines
OpenClaw instances
ACP-compatible CLIs
managed agent backends
```
Key principle:
> ACP is transport + call format + capability exposure. It is not the complete control plane.
The control plane still needs to own lifecycle, cancellation, recovery, placement, approval routing, event normalization, usage, and artifact ownership.
## Proposed Phases
### Phase 1: Formalize OpenClaw as a RuntimeAdapter
Move the existing OpenClaw Gateway execution path behind an explicit adapter boundary.
Constraints:
- No user-visible behavior change.
- Current local OpenClaw Gateway flow remains the default direct mode.
- Renderer/core code should stop reaching directly for OpenClaw wire concepts when a runtime-neutral method is enough.
Initial adapter shape:
```text
RuntimeAdapter
getRuntimeInfo()
getCapabilities()
createExecution()
cancelExecution()
resumeExecution()
sendInput()
streamEvents()
listChildren()
listApprovals()
resolveApproval()
listArtifacts()
getUsage()
getHealth()
```
### Phase 2: Add Execution as an internal control-plane object
Add local persistence for `Execution` and `RuntimeSessionRef`.
Keep `Task` as the top-level user-facing object, but stop treating it internally as exactly one OpenClaw session.
Target semantics:
- A Task can own one Execution.
- A Task can own multiple Executions.
- A TaskRoom performer can project any runtime execution, not only OpenClaw subagent sessions.
### Phase 3: Add ACPAdapter
Implement a local ACP runtime adapter that can start/connect to an ACP-compatible agent and normalize its output into ClawWork execution events.
MVP scope:
- create execution
- send input
- stream text delta/final
- cancel execution
- basic history/persistence through ClawWork local state
- capability reporting
Later scope:
- tool call/result events
- approval request/resolution
- artifacts
- resume
- usage/cost
- child execution/subagent projection
### Phase 4: Generalize TaskRoom and Teams
Move performer identity from "OpenClaw subagent session" to "runtime execution projected as a performer".
The Room/Team UX should remain task-first. Runtime-specific details stay behind adapters unless needed for debugging.
### Phase 5: Capability-based scheduling
Introduce runtime capability checks for routing and UI affordances.
Initial capabilities:
- streams text
- supports tool events
- supports approvals
- supports MCP/tools
- accesses filesystem
- constrains network
- supports resume
- produces artifacts
- reports usage/quota
- supports child executions/subagents
## Unified Event Model
Adapters should normalize runtime-native events into a small internal event set:
```text
execution.created
execution.started
execution.progress
execution.message.delta
execution.message.final
execution.thinking.delta
execution.tool.call
execution.tool.result
execution.approval.requested
execution.approval.resolved
execution.artifact.created
execution.warning
execution.error
execution.completed
execution.cancelled
execution.child.spawned
```
Partial capability is acceptable. Do not fake unsupported semantics; report unsupported capability explicitly.
## Non-goals
- Do not make ClawWork an OpenClaw admin console.
- Do not make ACP pretend to own lifecycle, placement, approval, or quota by itself.
- Do not introduce an OpenClaw Gateway compatibility facade as the long-term abstraction.
- Do not leak runtime-specific protocol details into renderer UI state.
- Do not weaken task/session isolation with hidden global runtime state.
## Acceptance Criteria
- Existing OpenClaw Gateway flow still works unchanged behind `OpenClawGatewayAdapter`.
- `Task` remains the primary product object, but internal execution state is no longer hard-bound to one OpenClaw session.
- A minimal ACP runtime can create an execution, receive input, stream output, cancel, and persist messages through the same product message model.
- Renderer logic consumes normalized execution/message/tool/approval events rather than switching on runtime-specific protocols.
- Runtime capabilities drive UI affordances and scheduling decisions.
## Notes
This is the long-term ClawWork Next path. A compatibility shim may still be useful for a throwaway proof, but it should not become the product architecture.
Contributor guide
Assessment
This issue has not been assessed yet.