138 lines
3.6 KiB
Markdown
138 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
<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:
|
|
|
|
```text
|
|
<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.
|