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**

```bash
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:

```bash
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:

```bash
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:

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

Expected: `LINK ./chrome` with exit code `0`.

**Step 6: Commit**

```bash
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:

```bash
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:

```bash
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**

```bash
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:

```bash
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:

```bash
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**

```bash
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:

```bash
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**

```bash
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:

```bash
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**

```bash
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:

```bash
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**

```bash
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?**