claw/docs/plans/2026-03-26-zeroclaw-core-refactor-plan.md

ZeroClaw Core Refactor Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Rebuild sgClaw on top of vendored ZeroClaw core while preserving the existing SuperRPA browser pipe protocol, FunctionsUI bridge names, and sgclaw binary contract.

Architecture: Keep sgclaw as the compatibility shell and replace its current minimal runtime with a ZeroClaw-based core adapter. Vendor the upstream ZeroClaw workspace into this repository for reproducible builds, then build a compat layer that translates submit_task / task_complete / log events to and from ZeroClaw agent, memory, cron, and tool abstractions. Do not integrate the upstream ZeroClaw gateway in this phase; the future standalone gateway will reuse the same vendored core through a separate entrypoint.

Tech Stack: Rust workspace, vendored upstream ZeroClaw (zeroclawlabs), current sgClaw pipe protocol and browser tool, DeepSeek via ZeroClaw provider routing, SQLite memory backends, Chromium run_cargo.py build flow.

Task 1: Vendor ZeroClaw Upstream Snapshot

Files:

• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/third_party/zeroclaw/**
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/third_party/zeroclaw/VENDORED_FROM.md
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/.gitignore

Step 1: Copy the upstream snapshot into the repo

Source:

/home/zyl/Downloads/zeroclaw-master.zip

Destination:

/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/third_party/zeroclaw

Strip the top-level zeroclaw-master/ folder so the vendored directory itself is the workspace root.

Step 2: Record provenance

Write third_party/zeroclaw/VENDORED_FROM.md with:

• upstream repo URL
• upstream default branch (master)
• source ZIP filename
• vendoring date
• a note that this copy is used to guarantee offline/reproducible browser builds

Step 3: Verify the vendor tree exists

Run:

find third_party/zeroclaw -maxdepth 2 -name Cargo.toml -o -name README.md

Expected: upstream workspace files are present.

Task 2: Convert sgClaw into a ZeroClaw-Backed Workspace Shell

Files:

• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/lib.rs
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/main.rs
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/mod.rs

Step 1: Add the vendored ZeroClaw dependency

Use a local path dependency:

zeroclaw = { package = "zeroclawlabs", path = "third_party/zeroclaw" }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Do not use a git dependency. Browser builds must not depend on network access.

Step 2: Preserve the root crate identity

Keep:

• package name sgclaw
• binary name sgclaw
• current manifest path used by SuperRPA browser build scripts

This avoids breaking /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/build_sgclaw.py.

Step 3: Route the process entrypoint through the compatibility layer

src/lib.rs should keep:

• current handshake
• current BrowserPipeTool
• current message loop

But delegate task execution to compat::runtime, not directly to the current thin planner/runtime path.

Task 3: Introduce the sgClaw Compatibility Layer

Files:

• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/runtime.rs
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/browser_tool_adapter.rs
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/config_adapter.rs
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/event_bridge.rs
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/memory_adapter.rs
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/agent/mod.rs

Step 1: Define the boundary

compat::runtime owns:

• creating the ZeroClaw config/provider/runtime/memory/tool registry
• executing a task from a browser submit_task
• translating ZeroClaw progress into current AgentMessage::LogEntry
• returning the final summary string for current task_complete

compat::event_bridge owns all formatting decisions for:

• [info] ...
• [error] ...
• final summary propagation

Step 2: Keep the browser protocol unchanged

Do not change these wire-level contracts:

• BrowserMessage::SubmitTask
• AgentMessage::TaskComplete
• AgentMessage::LogEntry
• init/init_ack

The browser side must not need a corresponding protocol change.

Step 3: Retire direct planner ownership from the main path

src/agent/mod.rs should stop owning the main task intelligence flow. The current rule-based planner can remain only as:

• transitional fallback, or
• deterministic test fixture

It must no longer be the primary execution engine.

Task 4: Adapt BrowserPipeTool into a ZeroClaw Tool

Files:

• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/browser_tool_adapter.rs
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/pipe/browser_tool.rs
• Test: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_browser_tool_test.rs

Step 1: Write the failing adapter test

Add a focused test that proves:

• a ZeroClaw tool invocation can issue navigate, type, click, getText
• domain validation still flows through current MAC/rules enforcement
• returned observation data includes browser response payload and AOM snapshot

Step 2: Verify RED

Run:

python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test \
  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
  --test compat_browser_tool_test

Expected: fail because the adapter does not exist yet.

Step 3: Implement the adapter

Wrap current BrowserPipeTool behind ZeroClaw’s async Tool trait:

• tool name should stay stable and sgClaw-specific, for example browser_action
• schema should only expose the currently supported safe actions
• ToolResult should include serialized data, aom_snapshot, timing

Task 5: Build the DeepSeek-Backed ZeroClaw Runtime Path

Files:

• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_runtime_test.rs
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/runtime.rs
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/config_adapter.rs
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/config/settings.rs

Step 1: Write the failing runtime test

Add a compatibility runtime test that proves:

• when DEEPSEEK_API_KEY is configured, sgClaw uses the ZeroClaw provider path
• the runtime can execute a simple mocked browser_action sequence
• the final result is returned as current sgClaw task_complete

Use a fake provider or deterministic ZeroClaw test seam for RED/GREEN speed.

Step 2: Verify RED

Run:

python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test \
  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
  --test compat_runtime_test

Expected: fail because the compatibility runtime is not wired yet.

Step 3: Implement DeepSeek mapping

Map current sgClaw env/config into ZeroClaw provider config:

• DEEPSEEK_API_KEY
• DEEPSEEK_BASE_URL
• DEEPSEEK_MODEL

DeepSeek should be treated as OpenAI-compatible routing under ZeroClaw, not via the old local DeepSeekProvider.

Task 6: Introduce Memory and Cron Through the Compatibility Core

Files:

• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/config_adapter.rs
• Modify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/memory_adapter.rs
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_memory_test.rs
• Create: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_cron_test.rs

Step 1: Memory

Configure a workspace-local ZeroClaw memory backend suitable for browser embedding:

• default to SQLite
• keep storage under sgClaw-owned data path
• avoid enabling unrelated gateway/channel storage

Step 2: Cron

Expose ZeroClaw cron internally, but do not yet bind it to browser UI. This phase only requires:

• creating validated agent jobs
• listing/running due jobs in tests

The future standalone gateway will surface management UI for cron.

Task 7: Verification and Browser Integration

Files:

• Verify: /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/*.rs
• Verify: /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/build_sgclaw.py
• Verify: /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs

Step 1: Run the full Rust test baseline

Run:

python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test \
  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
  --tests

Expected: current protocol/tool/planner compatibility tests still pass or are consciously replaced with equivalent compat tests.

Step 2: Build the browser-delivered binary from the worktree

Run:

python3 /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/build_sgclaw.py \
  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
  --out /home/zyl/projects/superRpa/src/out/KylinRelease/sgclaw

Expected: the compatibility-shell binary is produced at the same output path as today.

Step 3: Run browser smoke

Run:

node /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs

Expected:

• browser protocol still starts and stops correctly
• Baidu task still succeeds
• Zhihu task still succeeds
• no browser-side API/bridge changes are required

Non-Goals for This Refactor

• Do not replace the current SuperRPA browser protocol with ZeroClaw gateway protocols.
• Do not expose the upstream ZeroClaw web dashboard inside FunctionsUI.
• Do not ship the standalone gateway in this phase.
• Do not migrate browser-side code to a new transport.

Phase 2 After This Refactor

After this compatibility refactor is stable:

• add a separate gateway crate or binary that uses the same vendored ZeroClaw core
• expose memory/cron/agent management there
• keep browser-side sgclaw as a thin local execution shell