claw/docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md

sgClaw SuperRPA Runtime Config Design

Status: Draft frozen before implementation
Date: 2026-03-29

1. Goal

Freeze the runtime-boundary design before further implementation so Task 2+ do not drift back into browser-compiled behavior.

The design line is fixed:

• host keeps the security boundary.
• sgClaw keeps runtime behavior.
• frontend bundle keeps display rights only.
• High-frequency changes move to runtime-managed files whenever possible.

2. Ownership Split

2.1 host

SuperRPA as host owns only the trusted boundary:

• process spawning
• pipe lifecycle and session security
• browser / office capability exposure
• path validation for runtime-managed files
• fallback to bundled defaults when external files are missing or unsafe

host does not own planner policy, model routing, provider selection, skill orchestration, or business behavior.

2.2 sgClaw runtime

sgClaw owns runtime behavior:

• planner / executor orchestration
• provider list and active provider selection
• skill loading and prompt mode
• browser / office backend selection
• runtime profile behavior
• planner-first execution sequencing

2.3 frontend bundle

frontend bundle owns presentation only:

• render runtime state, logs, and conversation
• render planner output before execution
• collect user input and forward it through host events

frontend bundle must not:

• decide whether planner runs
• directly select provider/backend outside runtime contract
• bypass sgClaw / zeroclaw execution

3. Runtime-Managed Files

3.1 launch config

Owned by host, preferred path:

<profile>/superrpa/sgclaw_launch_config.json

Fields:

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

Fallback rules:

1. Prefer external launch config
2. Fall back to bundled browser defaults when file is missing or invalid
3. Fall back to profile-local runtime config if runtime_config_path is absent
4. Fall back to bundled frontend resources if frontend_bundle_dir is absent or invalid

3.2 runtime config

Owned by sgClaw, current default path:

<profile>/superrpa/sgclaw_config.json

This file should carry runtime behavior instead of browser compile-time constants, including:

• planner mode
• providers and active provider
• browser backend
• office backend
• skills prompt mode
• runtime profile

3.3 frontend bundle

Owned by host for loading, but externally replaceable at runtime:

• prefer frontend_bundle_dir
• validate path and allowed loading rules
• fall back to bundled resources if invalid

4. Planner-First Rule

planner-first is a runtime contract, not a frontend trick.

The sequence must be:

1. sgClaw / zeroclaw produces a plan
2. frontend bundle displays the plan
3. runtime continues into execution
4. acceptance verifies both visible plan rendering and actual execution ordering

5. Failing Checklist

The following questions remain intentionally unresolved at design-freeze time and must be closed by implementation plus verification:

• 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?

6. Terminology Guardrail

All related docs and code reviews must use the same terms:

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

Any proposal that moves planner or executor logic back into browser-side presentation code is out of bounds for this design.