clawwork-ai / clawwork-ai/ClawWork

Plan ClawWork Next RuntimeAdapter path for ACP multi-agent support

Open
#498 1 comment 0 reactions 1 assignee Claimed by @samzong View on GitHub
enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.