rrweb-skill/references/sgrobot-adapter.md

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:

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:

[[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:

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:

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