claw/docs/plans/2026-03-28-sgclaw-zeroclaw-core-realignment-plan.md

SGClaw ZeroClaw Core Realignment Implementation Plan

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

Goal: Rebuild sgclaw as a security-hardened zeroclaw runtime where the browser is a privileged tool surface and client host, not the product's defining execution model.

Architecture: zeroclaw remains the real agent core for prompt building, skills, memory, tool routing, autonomy, and execution loops. sgclaw adds a security envelope around zeroclaw: hardened configuration defaults, MAC-validated pipe communication, browser-host revalidation, and constrained exposure of privileged tools. The browser stays important, but only as one protected execution surface.

Tech Stack: Rust, vendored zeroclaw, SuperRPA browser pipe protocol, Chromium WebUI/overlay, JSON config, HMAC/MAC policy rules.

Scope Guard

• In scope:
  • zeroclaw-first runtime restructuring
  • security and tool policy layering
  • browser pipe re-framing as privileged tool surface
  • documentation correction before code changes
  • browser UI wording and observability alignment
• Out of scope:
  • broad UI redesign before the runtime contract is fixed
  • indiscriminately enabling every zeroclaw built-in tool
  • keeping parallel browser-only and zeroclaw-first runtime stacks long-term

Task 1: Rewrite The Product Docs Before Touching Runtime Code

Files:

• Modify: docs/README.md
• Modify: docs/L0-产品白皮书与能力全景层.md
• Modify: docs/L1-系统架构与安全模型层.md
• Modify: docs/L2-核心模块与接口契约层.md
• Modify: docs/L3-数据流与Skill体系层.md
• Modify: docs/L4-工程实现与部署拓扑层.md
• Modify: docs/L5-提示词分布与安全改造方案.md
• Modify: docs/浏览器对接标准.md

Intent:

• Make the docs the single source of truth before implementation starts.
• Remove the misleading framing that sgclaw is fundamentally a browser execution core.
• Replace it with the correct framing: sgclaw is a security-hardened zeroclaw distribution with a privileged browser execution surface.

Step 1: Add a docs checklist in the plan branch

Checklist to apply consistently across the docs:

1. zeroclaw is the runtime core
2. sgclaw adds security policy and protected execution surfaces
3. browser pipe is one privileged tool surface, not the whole runtime
4. docs must distinguish current implementation gaps from target architecture
5. no doc may imply that browser-only compat is the desired end state

Step 2: Update the architecture docs

Required wording changes:

• Replace phrases equivalent to “浏览器智能体执行内核” with wording equivalent to “安全加固后的 zeroclaw runtime”.
• Reframe compat as a temporary adaptation layer, not the final product identity.
• Clarify that browser_action is a protected tool contract, not the only capability sgClaw should ever have.
• Clarify that prompt治理、安全摘要、skills、memory、routing should stay aligned with zeroclaw-native mechanisms.

Step 3: Run doc consistency checks

Run:

rg -n "浏览器智能体执行内核|单一 `browser_action` 工具|兼容执行器" docs
rg -n "zeroclaw.*核心|特权工具面|安全加固" docs

Expected:

• The first command should only return historical or explicitly marked current-state references.
• The second command should show the new target framing in the mainline docs.

Step 4: Commit

git add docs/README.md docs/L0-产品白皮书与能力全景层.md docs/L1-系统架构与安全模型层.md docs/L2-核心模块与接口契约层.md docs/L3-数据流与Skill体系层.md docs/L4-工程实现与部署拓扑层.md docs/L5-提示词分布与安全改造方案.md docs/浏览器对接标准.md
git commit -m "docs: redefine sgclaw as hardened zeroclaw runtime"

Task 2: Introduce A Zeroclaw-First Runtime Module

Files:

• Create: src/runtime/mod.rs
• Create: src/runtime/profile.rs
• Create: src/runtime/tool_policy.rs
• Create: src/runtime/engine.rs
• Modify: src/lib.rs
• Test: tests/runtime_profile_test.rs

Intent:

• Create a real runtime namespace that represents sgClaw’s zeroclaw-first architecture.
• Stop letting compat/runtime.rs be the place where product architecture is defined.

Step 1: Write the failing tests

Create tests/runtime_profile_test.rs with at least:

#[test]
fn browser_attached_profile_exposes_browser_surface_without_becoming_browser_only() {
    let profile = RuntimeProfile::BrowserAttached;
    let policy = ToolPolicy::for_profile(profile);

    assert!(policy.allowed_tools.contains("browser_action"));
    assert!(policy.may_use_non_browser_tools);
}

#[test]
fn general_assistant_profile_does_not_require_browser_surface() {
    let profile = RuntimeProfile::GeneralAssistant;
    let policy = ToolPolicy::for_profile(profile);

    assert!(!policy.requires_browser_surface);
}

Step 2: Run the tests to confirm failure

Run:

cargo test --test runtime_profile_test -- --nocapture

Expected:

• Fail with unresolved imports or missing types for RuntimeProfile and ToolPolicy.

Step 3: Add the minimal runtime module

Implement the first-pass skeleton:

pub enum RuntimeProfile {
    BrowserAttached,
    BrowserHeavy,
    GeneralAssistant,
}

pub struct ToolPolicy {
    pub requires_browser_surface: bool,
    pub may_use_non_browser_tools: bool,
    pub allowed_tools: Vec<String>,
}

Step 4: Re-run the focused tests

Run:

cargo test --test runtime_profile_test -- --nocapture

Expected:

• Both new tests pass.

Step 5: Commit

git add src/runtime/mod.rs src/runtime/profile.rs src/runtime/tool_policy.rs src/runtime/engine.rs src/lib.rs tests/runtime_profile_test.rs
git commit -m "feat: add zeroclaw-first runtime module skeleton"

Task 3: Replace DeepSeek-Only Settings With Zeroclaw-First SGClaw Settings

Files:

• Modify: src/config/settings.rs
• Modify: src/config/mod.rs
• Modify: src/compat/config_adapter.rs
• Test: tests/compat_config_test.rs
• Test: tests/compat_memory_test.rs
• Test: tests/compat_cron_test.rs

Intent:

• Stop treating browser config as only a DeepSeek shim.
• Introduce sgClaw settings that can express zeroclaw-first runtime behavior while staying backward-compatible with the existing sgclaw_config.json.

Step 1: Add the failing config tests

Add tests beside the existing ones in tests/compat_config_test.rs:

#[test]
fn sgclaw_settings_default_to_compact_skills_and_browser_attached_profile() {
    let settings = SgClawSettings::from_legacy_deepseek_fields(
        "sk-test".into(),
        "https://api.deepseek.com".into(),
        "deepseek-chat".into(),
        None,
    ).unwrap();

    assert_eq!(settings.runtime_profile, RuntimeProfile::BrowserAttached);
    assert_eq!(settings.skills_prompt_mode, SkillsPromptMode::Compact);
}

#[test]
fn sgclaw_settings_load_new_runtime_fields_from_browser_config() {
    // write config with runtimeProfile / skillsPromptMode / allowedToolProfiles
}

Step 2: Run the focused tests

Run:

cargo test --test compat_config_test -- --nocapture

Expected:

• Fail because SgClawSettings, RuntimeProfile, or new parsing fields do not exist yet.

Step 3: Implement backward-compatible settings expansion

Minimal target shape:

pub struct SgClawSettings {
    pub provider_api_key: String,
    pub provider_base_url: String,
    pub provider_model: String,
    pub skills_dir: Option<PathBuf>,
    pub skills_prompt_mode: SkillsPromptMode,
    pub runtime_profile: RuntimeProfile,
}

Compatibility rules:

• Existing apiKey/baseUrl/model/skillsDir continue to load.
• New fields such as skillsPromptMode and runtimeProfile are optional.
• Defaults should be hardened, not legacy-full-prompt by accident.

Step 4: Run the config and adapter tests

Run:

cargo test --test compat_config_test -- --nocapture
cargo test --test compat_memory_test -- --nocapture
cargo test --test compat_cron_test -- --nocapture

Expected:

• All pass.

Step 5: Commit

git add src/config/settings.rs src/config/mod.rs src/compat/config_adapter.rs tests/compat_config_test.rs tests/compat_memory_test.rs tests/compat_cron_test.rs
git commit -m "feat: add zeroclaw-first sgclaw settings model"

Task 4: Rebuild The Execution Path Around The New Runtime Engine

Files:

• Modify: src/compat/runtime.rs
• Modify: src/agent/mod.rs
• Modify: src/compat/event_bridge.rs
• Test: tests/compat_runtime_test.rs

Intent:

• Make compat/runtime.rs a thin bridge into the new runtime engine instead of the place where the product’s core execution policy lives.
• Keep browser-originated tasks attached to a browser surface, but do not collapse the runtime into a browser-only tool list.

Step 1: Add the failing runtime tests

Extend tests/compat_runtime_test.rs with at least:

#[test]
fn compat_runtime_can_complete_a_text_only_turn_without_browser_tool_calls() {
    // provider returns direct assistant content
    // no BrowserMessage::Response is queued
    // summary should still succeed
}

#[test]
fn compat_runtime_allows_read_skill_under_compact_mode_policy() {
    // configure compact skills mode
    // verify the runtime tool policy includes read_skill
}

Step 2: Run the focused runtime test file

Run:

cargo test --test compat_runtime_test -- --nocapture

Expected:

• Fail because the current runtime still hardcodes browser-only exposure or cannot express the new policy.

Step 3: Refactor the runtime path

Implementation target:

• src/agent/mod.rs decides the runtime profile and passes browser context into the runtime engine.
• src/compat/runtime.rs becomes a compatibility bridge, not the architecture center.
• src/runtime/engine.rs owns:
  • zeroclaw agent creation
  • tool registration
  • skill loading
  • runtime profile application
  • browser contract prompt injection only when browser surface is actually present

Step 4: Re-run the focused runtime tests

Run:

cargo test --test compat_runtime_test -- --nocapture

Expected:

• Existing compat runtime tests still pass.
• New text-only / compact-skill tests pass.

Step 5: Commit

git add src/compat/runtime.rs src/agent/mod.rs src/compat/event_bridge.rs tests/compat_runtime_test.rs
git commit -m "refactor: route browser requests through zeroclaw-first runtime engine"

Task 5: Treat The Browser Pipe As A Privileged Tool Surface

Files:

• Modify: src/compat/browser_tool_adapter.rs
• Modify: src/pipe/protocol.rs
• Modify: src/pipe/browser_tool.rs
• Modify: src/security/mac_policy.rs
• Test: tests/compat_browser_tool_test.rs
• Test: tests/browser_tool_test.rs
• Test: tests/pipe_protocol_test.rs
• Test: tests/pipe_handshake_test.rs

Intent:

• Keep the browser powerful, but explicitly as a protected external execution surface.
• Preserve the current HMAC/MAC/rules boundary while making it obvious in code that browser execution is not synonymous with runtime execution.

Step 1: Add the failing tests

Examples:

#[test]
fn browser_tool_contract_is_marked_as_privileged_surface_in_policy_metadata() {
    // assert runtime metadata treats browser tool separately from generic tools
}

#[test]
fn browser_submit_task_can_carry_browser_context_without_forcing_browser_only_execution() {
    // protocol/adapter level test
}

Step 2: Run the safety-related tests

Run:

cargo test --test compat_browser_tool_test -- --nocapture
cargo test --test browser_tool_test -- --nocapture
cargo test --test pipe_protocol_test -- --nocapture
cargo test --test pipe_handshake_test -- --nocapture

Expected:

• Fail on new privilege/metadata expectations before implementation.

Step 3: Implement the policy split

Implementation target:

• keep browser_action schema constrained
• keep MacPolicy as the final guard on outbound browser commands
• annotate browser surface metadata in the runtime/tool policy layer
• avoid leaking browser-only assumptions into generic runtime config

Step 4: Re-run the focused browser safety tests

Run the same four commands from Step 2.

Expected:

• All pass.

Step 5: Commit

git add src/compat/browser_tool_adapter.rs src/pipe/protocol.rs src/pipe/browser_tool.rs src/security/mac_policy.rs tests/compat_browser_tool_test.rs tests/browser_tool_test.rs tests/pipe_protocol_test.rs tests/pipe_handshake_test.rs
git commit -m "feat: model browser pipe as privileged runtime surface"

Task 6: Restore Zeroclaw-Native Skills Instead Of Browser-Specific Skill Prompt Hacks

Files:

• Modify: src/runtime/engine.rs
• Modify: src/compat/event_bridge.rs
• Modify: src/agent/mod.rs
• Test: tests/compat_runtime_test.rs
• Test: tests/skill_lib_validation_test.py

Intent:

• Make skill loading and skill usage follow zeroclaw-native behavior first.
• Prefer compact mode plus read_skill when safe.
• Make skill usage observable in runtime logs so the browser UI can explain what happened.

Step 1: Add the failing skill-observability tests

Add tests for:

• compact mode includes read_skill
• runtime logs show when read_skill or skill-defined tools are invoked
• configured skillsDir still resolves both repo-root and nested skills/ layouts

Step 2: Run the skill-related tests

Run:

cargo test --test compat_runtime_test -- --nocapture
python3 tests/skill_lib_validation_test.py

Expected:

• New observability assertions fail before implementation.

Step 3: Implement the minimal skill-first runtime behavior

Implementation target:

• compact skills mode becomes the sgClaw default unless explicitly overridden
• read_skill is allowed when the active tool policy permits it
• runtime logs include loaded skill names and actual skill/tool usage

Step 4: Re-run the skill tests

Run the same two commands from Step 2.

Expected:

• Both pass.

Step 5: Commit

git add src/runtime/engine.rs src/compat/event_bridge.rs src/agent/mod.rs tests/compat_runtime_test.rs tests/skill_lib_validation_test.py
git commit -m "feat: restore zeroclaw-native skill flow and observability"

Task 7: Remove Or Quarantine The Legacy Parallel Runtime Paths

Files:

• Modify or delete: src/agent/runtime.rs
• Modify or delete: src/agent/planner.rs
• Modify: tests/agent_runtime_test.rs
• Modify: tests/planner_test.rs
• Modify: docs/L2-核心模块与接口契约层.md
• Modify: docs/L3-数据流与Skill体系层.md

Intent:

• Stop shipping multiple conceptual runtimes.
• If the light runtime/planner path still has value, mark it as legacy/dev-only.
• If it has no production value, remove it after the zeroclaw-first runtime is stable.

Step 1: Decide the disposition

Choose one:

A. delete planner/runtime legacy path
B. keep as explicit legacy/dev-only module with zero production routing

Recommendation: B first, then A after one clean release cycle.

Step 2: Add the failing cleanup tests

Examples:

• production browser path never routes into planner fallback
• docs no longer describe planner fallback as the primary model-enabled path

Step 3: Run the legacy-path tests

Run:

cargo test --test agent_runtime_test -- --nocapture
cargo test --test planner_test -- --nocapture

Expected:

• Fail once the cleanup assertions are added.

Step 4: Apply the cleanup

Implementation target:

• remove production routing dependency
• rename or mark legacy modules clearly
• update docs to match the new reality

Step 5: Re-run the legacy-path tests and commit

Run the same two commands, then:

git add src/agent/runtime.rs src/agent/planner.rs tests/agent_runtime_test.rs tests/planner_test.rs docs/L2-核心模块与接口契约层.md docs/L3-数据流与Skill体系层.md
git commit -m "refactor: quarantine legacy browser-only runtime paths"

Task 8: Align The Browser UI With The New Runtime Truth

Files:

• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts
• Modify: /home/zyl/projects/superRpa/src/AGENTS.md

Intent:

• Make the browser UI an honest client of the runtime.
• Stop labeling all tasks as “网页执行” when the runtime may have solved them through non-browser zeroclaw capabilities.

Step 1: Add the UI contract checklist

Checklist:

1. UI shows runtime profile or capability mode
2. UI can show whether browser tools were actually used
3. UI can show when skills were read or invoked
4. wording does not imply browser is the whole runtime

Step 2: Implement the label and observability changes

Examples:

• replace fixed “网页执行” copy with runtime-derived capability wording
• add a compact “本轮调用”/“能力来源” section
• avoid implying every successful task came from page automation

Step 3: Verify browser resources

Run:

node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome

Expected:

• All pass.

Step 4: Commit

git -C /home/zyl/projects/superRpa/src add chrome/browser/resources/superrpa/sgclaw_overlay.js chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts AGENTS.md
git -C /home/zyl/projects/superRpa/src commit -m "feat: align browser ui with zeroclaw-first runtime"

Final Verification Matrix

Run, in order:

cargo test --test runtime_profile_test -- --nocapture
cargo test --test compat_config_test -- --nocapture
cargo test --test compat_runtime_test -- --nocapture
cargo test --test compat_browser_tool_test -- --nocapture
cargo test --test browser_tool_test -- --nocapture
cargo test --test pipe_protocol_test -- --nocapture
cargo test --test pipe_handshake_test -- --nocapture
cargo test --test agent_runtime_test -- --nocapture
cargo test --test planner_test -- --nocapture
python3 tests/skill_lib_validation_test.py

If local Cargo registry state is unstable, use the Chromium hermetic wrapper instead:

python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test --manifest-path /home/zyl/projects/sgClaw/claw/Cargo.toml -- --nocapture

Then verify browser integration:

node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome

Success Criteria

• The docs say the right thing before the code change begins.
• sgclaw behaves like a security-hardened zeroclaw runtime, not a browser-only compat shell.
• The browser pipe remains central for protected execution, but it is no longer mistaken for the whole product architecture.
• Skills, prompt building, memory, routing, and tool policy all flow through zeroclaw-native mechanisms first.
• The UI becomes a thin, honest client of the shared runtime.