# SGrobot Adapter Reference

## Boundary

SGrobot uses two runtime artifact families:

- `plan_templates/<task>/PlanTemplate.toml`: business orchestration, selectable as a digital employee task.
- `.sgclaw-workspace/skills/<skill>/SKILL.toml`: atomic runtime capability loaded by Skill Catalog.

The Codex-facing `SKILL.md` in this repository only teaches an agent how to generate those artifacts.

## Generated Flow Shape

For each rrweb semantic trace, generate one business-specific package:

```text
plan_templates/rrweb-<flow>/PlanTemplate.toml
.sgclaw-workspace/skills/rrweb-<flow>-execute/SKILL.toml
.sgclaw-workspace/skills/rrweb-<flow>-execute/scripts/execute_trace.js
.sgclaw-workspace/skills/rrweb-<flow>-execute/trace.semantic.json
```

Do not generate a single universal runtime skill that expects `trace_path` unless SGrobot core gains stable per-step argument passing. Current stable PlanTemplate usage binds a step to a skill name; the runtime resolves that skill's primary tool.

## PlanTemplate Mapping

Use three steps:

1. `open-target-page`: `skills = ["browser.open_url"]`; description includes the trace `startUrl`.
2. `run-recorded-flow`: `skills = ["rrweb-<flow>-execute"]`; executes generated page script with sgBrowser.
3. `save-result`: `skills = ["json.save_result"]`; saves structured output.

Set `requires_approval = true` on `run-recorded-flow` when `--default-mode execute` is used and the trace includes mutating actions such as `click`, `fill`, `select`, `check`, `submit`, or `risk = "write"`.

## Runtime Skill Mapping

Generated `SKILL.toml` should use:

```toml
[[tools]]
name = "execute_trace"
kind = "sgbrowser_action"
command = "sgBrowserExcuteJsCodeByDomain"
expected_domain = "<domain from startUrl>"

[tools.args]
script_path = "scripts/execute_trace.js"
```

Keep `sgBrowserExcuteJsCodeByDomain` and the `sgBrowerserOpenPage` spelling used by the existing SGrobot project. Do not replace this path with Playwright, CDP, or a generic browser action.

## Runtime Script Rules

The generated `execute_trace.js` runs inside the target page. It should:

- Default to `dry-run` unless the generator is called with `--default-mode execute`.
- Resolve target elements by stable CSS selector first, XPath second, visible text fallback last.
- Return structured JSON with `ok`, `mode`, `trace_id`, `url`, `title`, and per-action results.
- Stop on the first failed action and include an error message.

## Verification

After generating into a SGrobot repo:

```bash
node scripts/generate_sgrobot_flow.mjs --trace examples/basic-trace.json --out /Users/zhaoyilun/projects/sgrobot-architecture-design --default-mode dry-run
```

Then verify in SGrobot:

```powershell
Invoke-RestMethod 'http://127.0.0.1:42617/api/debug/plans?limit=20' | ConvertTo-Json -Depth 5
Invoke-RestMethod 'http://127.0.0.1:42617/api/skill' | ConvertTo-Json -Depth 4
```