claw/docs/plans/2026-03-29-sgclaw-superrpa-decoupled-runtime-plan.md

sgClaw SuperRPA Decoupled Runtime Implementation Plan

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

Goal: Keep the SuperRPA parent-child security model, while moving high-frequency sgClaw startup, model, skill, and frontend presentation changes out of SuperRPA compile-time code and into runtime-managed configuration.

Architecture: SuperRPA remains the trusted host that owns process spawning, pipe security, browser/office capability gates, and frontend host contracts. sgClaw becomes the runtime-configured execution engine that reads launch/runtime policy from files, with SuperRPA preferring external launch descriptors and external frontend bundles before falling back to bundled defaults. This preserves the security boundary while removing the need to rebuild the browser for routine sgClaw iteration.

Tech Stack: Chromium C++ WebUI, TypeScript/Lit frontend, Rust sgClaw runtime, JSON config files, local filesystem-based runtime assets, existing pipe protocol and Zeroclaw planner-first execution path.

Task 1: Freeze the design in docs before further code changes

Files:

• Modify: /home/zyl/projects/sgClaw/claw/docs/L1-系统架构与安全模型层.md
• Modify: /home/zyl/projects/sgClaw/claw/docs/L2-核心模块与接口契约层.md
• Modify: /home/zyl/projects/sgClaw/claw/docs/L4-工程实现与部署拓扑层.md
• Create: /home/zyl/projects/sgClaw/claw/docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md

Step 1: Write the design delta doc

Document these decisions explicitly:

• SuperRPA owns host security and capability exposure only.
• sgClaw owns planner, model routing, skill orchestration, and business behavior.
• Launch behavior is described by runtime files, not hardcoded browser-side constants.
• Frontend only has display rights; planner/executor decisions stay in sgClaw/Zeroclaw.

Step 2: Add the failing doc checklist

Create a checklist inside the design doc with these questions and mark them initially unresolved:

• Can browser startup switch sgClaw binary without rebuilding Chromium?
• Can model/provider selection change without rebuilding Chromium?
• Can floating UI be replaced without rebuilding Chromium?
• Can acceptance flows prove planner-first behavior visually and functionally?

Step 3: Update the core architecture docs

Add short sections showing:

• Launch config file path and fallback rules.
• Runtime config ownership split between SuperRPA and sgClaw.
• External frontend bundle loading path and fallback to bundled assets.

Step 4: Review docs for consistency

Check that L1, L2, L4, and the new design doc all use the same terms:

• host
• launch config
• runtime config
• frontend bundle
• planner-first

Step 5: Commit

git -C /home/zyl/projects/sgClaw/claw add \
  docs/L1-系统架构与安全模型层.md \
  docs/L2-核心模块与接口契约层.md \
  docs/L4-工程实现与部署拓扑层.md \
  docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md
git -C /home/zyl/projects/sgClaw/claw commit -m "docs: define superrpa sgclaw runtime boundary"

Task 2: Finish and lock down the current stale-backend fix

Files:

• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_session_service.cc
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_session_service.h
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/functions_ui_mainline_unittest.cc
• Create: /home/zyl/projects/sgClaw/claw/tools/browser_runtime/sgclaw_browser_entry.sh

Step 1: Write the failing regression test

Add internal tests for binary resolution priority:

1. SUPERRPA_SGCLAW_BINARY override wins.
2. skillsDir-inferred source checkout wrapper wins over bundled binary.
3. Bundled out/.../sgclaw is only a fallback.

Step 2: Run the failing test

Run:

autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease functions_ui_mainline_unittests
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests --gtest_filter="SgClawSessionServiceInternalTest.*"

Expected: the new test target fails before the final test helper wiring is complete.

Step 3: Write the minimal implementation

Expose a testable internal resolver function that accepts:

• config path
• bundled binary path
• optional env override string
• output detail string

Keep production Start() calling the same shared resolver to avoid divergence.

Step 4: Run tests to verify they pass

Run:

autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease functions_ui_mainline_unittests
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests --gtest_filter="SgClawSessionServiceInternalTest.*:FunctionsUiMainlineTest.StartPublishesDetailedRulesDiagnosticsToUiLogs"

Expected: all targeted tests pass.

Step 5: Run browser compile verification

Run:

autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome

Expected: LINK ./chrome with exit code 0.

Step 6: Commit

git -C /home/zyl/projects/superRpa/src add \
  chrome/browser/ui/webui/superrpa/sgclaw_session_service.cc \
  chrome/browser/ui/webui/superrpa/sgclaw_session_service.h \
  chrome/browser/ui/webui/superrpa/functions_ui_mainline_unittest.cc
git -C /home/zyl/projects/sgClaw/claw add \
  tools/browser_runtime/sgclaw_browser_entry.sh
git -C /home/zyl/projects/superRpa/src commit -m "superrpa: resolve sgclaw binary from runtime config"

Task 3: Add a real launch descriptor so SuperRPA no longer hardcodes sgClaw startup policy

Files:

• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_webui_config.h
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_webui_config.cc
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_session_service.cc
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/functions_ui.cc
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config_state.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config_mainline_unittest.ts
• Create: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_launch_config.h
• Create: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_launch_config.cc
• Test: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/functions_ui_mainline_unittest.cc

Step 1: Write the failing config tests

Cover:

• missing launch config falls back safely
• explicit binary, args, env, working_dir, runtime_config_path parse correctly
• unsafe or nonexistent paths are rejected with clear UI-visible errors

Step 2: Run the failing tests

Run:

autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease functions_ui_mainline_unittests
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests --gtest_filter="*SgClaw*Config*"

Expected: launch-config cases fail before parser/consumer code is added.

Step 3: Implement minimal launch config support

Define a host-side launch descriptor with fields:

• binary
• args
• env
• working_dir
• runtime_config_path
• frontend_bundle_dir

Load it from a predictable profile-local path, with safe defaults and fallback to existing behavior.

Step 4: Wire startup to the descriptor

Have SgClawSessionService::Start() resolve:

• executable path
• process args
• working dir
• env
• runtime config path

without requiring browser recompilation for routine changes.

Step 5: Wire config UI to persist supported fields

Make sgclaw-config save and load the new fields so local users can adjust launch behavior from the UI or by editing the JSON file directly.

Step 6: Run tests and browser compile

Run:

autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease functions_ui_mainline_unittests chrome

Expected: config tests pass and browser still links.

Step 7: Commit

git -C /home/zyl/projects/superRpa/src add \
  chrome/browser/ui/webui/superrpa/sgclaw_launch_config.h \
  chrome/browser/ui/webui/superrpa/sgclaw_launch_config.cc \
  chrome/browser/ui/webui/superrpa/sgclaw_webui_config.h \
  chrome/browser/ui/webui/superrpa/sgclaw_webui_config.cc \
  chrome/browser/ui/webui/superrpa/sgclaw_session_service.cc \
  chrome/browser/ui/webui/superrpa/functions_ui.cc \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config.ts \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config_state.ts \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config_mainline_unittest.ts
git -C /home/zyl/projects/superRpa/src commit -m "superrpa: add runtime launch config for sgclaw"

Task 4: Expand sgClaw runtime config so model/provider/skill policy live in sgClaw, not SuperRPA

Files:

• Modify: /home/zyl/projects/sgClaw/claw/src/config/settings.rs
• Modify: /home/zyl/projects/sgClaw/claw/src/config/mod.rs
• Modify: /home/zyl/projects/sgClaw/claw/src/compat/config_adapter.rs
• Modify: /home/zyl/projects/sgClaw/claw/src/agent/runtime.rs
• Modify: /home/zyl/projects/sgClaw/claw/src/agent/planner.rs
• Modify: /home/zyl/projects/sgClaw/claw/tests/compat_config_test.rs
• Modify: /home/zyl/projects/sgClaw/claw/tests/runtime_profile_test.rs
• Modify: /home/zyl/projects/sgClaw/claw/tests/planner_test.rs
• Modify: /home/zyl/projects/sgClaw/claw/docs/L3-数据流与Skill体系层.md

Step 1: Write failing Rust tests

Cover config-driven behavior for:

• planner-first mode
• provider list / active provider
• browser backend selection
• office backend selection
• skills prompt mode
• runtime profile

Step 2: Run the failing tests

Run:

cargo test compat_config_test runtime_profile_test planner_test --manifest-path /home/zyl/projects/sgClaw/claw/Cargo.toml

Expected: new config fields are missing or ignored.

Step 3: Implement minimal config schema changes

Add fields that let sgClaw choose behavior without host rebuild:

• planner_mode
• providers
• active_provider
• browser_backend
• office_backend
• skills_prompt_mode
• runtime_profile

Step 4: Keep Zeroclaw-first execution

Ensure the planner reads config before execution and produces a visible plan event for the frontend, but the frontend still only renders what sgClaw emits.

Step 5: Re-run Rust tests

Run:

cargo test --manifest-path /home/zyl/projects/sgClaw/claw/Cargo.toml compat_config_test runtime_profile_test planner_test runtime_task_flow_test

Expected: planner/config tests pass.

Step 6: Commit

git -C /home/zyl/projects/sgClaw/claw add \
  src/config/settings.rs \
  src/config/mod.rs \
  src/compat/config_adapter.rs \
  src/agent/runtime.rs \
  src/agent/planner.rs \
  tests/compat_config_test.rs \
  tests/runtime_profile_test.rs \
  tests/planner_test.rs \
  docs/L3-数据流与Skill体系层.md
git -C /home/zyl/projects/sgClaw/claw commit -m "sgclaw: move runtime policy into config"

Task 5: Decouple the floating UI so visual iteration stops depending on Chromium rebuilds

Files:

• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_state.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/functions_ui.cc
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_session_service.cc
• Create: /home/zyl/projects/sgClaw/claw/frontend/runtime-host/README.md
• Create: /home/zyl/projects/sgClaw/claw/frontend/runtime-host/manifest.example.json

Step 1: Write failing UI host tests

Cover:

• external frontend bundle dir is preferred when declared in launch config
• bundled frontend assets still load when external assets are absent
• planner events are rendered as plan cards/log lines before execution

Step 2: Run the failing frontend/browser tests

Run:

autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome/test/data/webui_test_resources

Then run the relevant TypeScript tests already wired for the sgClaw chat surface.

Step 3: Implement the minimal external bundle loader

SuperRPA should:

• keep the host shell and JS bridge fixed
• optionally load external sgclaw-chat assets from runtime-configured directory
• fall back to bundled assets when missing

Step 4: Surface planner output early

Use existing runtime event flow so the frontend shows:

• plan summary
• current step
• execution logs

without moving control logic into the frontend.

Step 5: Re-run tests

Run the existing sgClaw chat WebUI tests and a browser smoke.

Step 6: Commit

git -C /home/zyl/projects/superRpa/src add \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_state.ts \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts \
  chrome/browser/ui/webui/superrpa/functions_ui.cc \
  chrome/browser/ui/webui/superrpa/sgclaw_session_service.cc
git -C /home/zyl/projects/sgClaw/claw add \
  frontend/runtime-host/README.md \
  frontend/runtime-host/manifest.example.json
git -C /home/zyl/projects/superRpa/src commit -m "superrpa: support external sgclaw frontend bundle"

Task 6: Close the current remaining behavioral gaps before new feature work

Files:

• Modify: /home/zyl/projects/sgClaw/claw/tests/live_acceptance_score_test.py
• Modify: /home/zyl/projects/sgClaw/claw/tools/live_acceptance/run_zhihu_hotlist_excel_acceptance.py
• Modify: /home/zyl/projects/sgClaw/claw/docs/acceptance/2026-03-29-zhihu-hotlist-excel.md
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_messages.ts

Step 1: Write failing acceptance assertions

Add explicit checks for:

• no repeated assistant paragraphs
• no fake fallback data when browser path exists
• planner-first output appears before tool execution
• Zhihu hotlist extraction returns structured rows
• office export returns a real output path

Step 2: Run the failing acceptance flow

Run:

python3 /home/zyl/projects/sgClaw/claw/tools/live_acceptance/run_zhihu_hotlist_excel_acceptance.py

Expected: current score exposes the remaining regressions if they still exist.

Step 3: Fix the smallest issue set first

Order:

1. repeated message rendering / repeated summary emission
2. planner event visibility
3. structured hotlist extraction handoff
4. office export path propagation

Step 4: Re-run acceptance

Run the same command until:

• hotlist_data_correctness > 0
• xlsx_export_success > 0
• repeated text is absent

Step 5: Record fresh evidence

Update the acceptance markdown with:

• timestamp
• score
• exact exported path
• screenshot/log snippets

Step 6: Commit

git -C /home/zyl/projects/sgClaw/claw add \
  tests/live_acceptance_score_test.py \
  tools/live_acceptance/run_zhihu_hotlist_excel_acceptance.py \
  docs/acceptance/2026-03-29-zhihu-hotlist-excel.md
git -C /home/zyl/projects/superRpa/src add \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
  chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_messages.ts
git -C /home/zyl/projects/sgClaw/claw commit -m "acceptance: stabilize zhihu hotlist excel flow"

Task 7: Final integrated verification

Files:

• Verify only: /home/zyl/projects/sgClaw/claw/docs/acceptance/2026-03-29-zhihu-hotlist-excel.md
• Verify only: /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/sgclaw_session_service.cc
• Verify only: /home/zyl/projects/sgClaw/claw/tools/browser_runtime/sgclaw_browser_entry.sh

Step 1: Build all affected binaries

Run:

autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome functions_ui_mainline_unittests
cargo test --manifest-path /home/zyl/projects/sgClaw/claw/Cargo.toml

Expected: both complete successfully.

Step 2: Do the live browser smoke

Run browser with the local profile and verify the logs include one of:

• using SUPERRPA_SGCLAW_BINARY override: ...
• using source checkout sgclaw inferred from skillsDir: ...
• using bundled sgclaw from browser output dir: ...

The expected dev mode result is the source checkout path, not the stale bundled fallback.

Step 3: Run the final business acceptance

Ask sgClaw to:

1. read Zhihu hotlist
2. export Excel
3. open the screen presentation in a new tab

Verify:

• planner appears first
• skills are actually used
• exported file path is returned
• new-tab presentation opens

Step 4: Record the result

Append the final evidence to:

• /home/zyl/projects/sgClaw/claw/docs/acceptance/2026-03-29-zhihu-hotlist-excel.md

Step 5: Commit

git -C /home/zyl/projects/sgClaw/claw commit -m "chore: record final sgclaw superrpa runtime verification"

Remaining Items Explicitly Carried Into This Plan

• The current stale-backend risk is not considered closed until the resolver has automated regression coverage.
• The current local edit in /home/zyl/projects/superRpa/src/chrome/browser/ui/webui/superrpa/functions_ui_mainline_unittest.cc must be either completed under Task 2 or replaced with the final tested version.
• The current wrapper script /home/zyl/projects/sgClaw/claw/tools/browser_runtime/sgclaw_browser_entry.sh is still untracked and must be committed as part of Task 2.
• The Zhihu hotlist to Excel acceptance still has unresolved correctness and export-path gaps and remains part of the critical path.
• The repeated assistant text regression remains part of the critical path because it corrupts operator trust during demos.

Plan complete and saved to docs/plans/2026-03-29-sgclaw-superrpa-decoupled-runtime-plan.md. Two execution options:

1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration

2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints

Which approach?