/sn-ppt-workbench

name: sn-ppt-workbench
description: Use when the user asks to open, preview, inspect, or visually edit an existing SenseNova HTML presentation in the PPT Workbench, using an explicit deck_dir or the latest deck in the current workspace.
metadata:
  project: SenseNova-Skills
  tier: aux
  category: ppt
  user_visible: true

sn-ppt-workbench

Start or reuse the AI PPT editing WebUI for an existing HTML slide deck. The helper prefers Hermes/canvas/port-forward URLs when available. Without a forwarded URL, native hosts bind to localhost by default, while Docker/WSL bind to `0.0.0.0` so remote users can reach the WebUI through the host network.

Use Cases

• The user already generated a deck and asks to open the WebUI/editor/workbench.
• The user provides a `deck_dir` containing `task_pack.json`,

`slides/slide_NN.html`, `pages/page_NNN.html`, or a root-level HTML deck.

• The user says to inspect or edit previously generated slides without regenerating them.

Hard Rules

1. Do not run `sn-ppt-entry`, `sn-ppt-standard`, `page-html`, `batch-page-html`, or `export`. 2. Do not edit slide files directly. The WebUI handles user-visible editing. 3. If `deck_dir` is missing, auto-detect only under `$(pwd)/ppt_decks`. Other roots are considered only when the caller explicitly passes `--search-root`; never scan home folders by default. 4. If no usable deck is found, ask the user for the absolute `deck_dir`. 5. Workbench startup is best-effort. If it skips or fails, report the reason and do not attempt generation as a fallback. 6. Prefer a forwarded/canvas URL over localhost when the user may be on SSH, IM, or another remote device. 7. When launched from the unified PPT flow, use the exact absolute `task_pack.deck_dir`; opening the Workbench must not create or switch tasks. 8. Treat `task_pack.json` as progress/resume state and `outline.md` as the user-editable Story. Existing runtime builds may expose only part of these artifacts; report compatibility gaps instead of regenerating the deck.

Invocation

Use the helper directly:

python3 $SKILL_DIR/scripts/open_workbench.py --deck-dir "<deck_dir>" --agent-session-id "${HERMES_SESSION_KEY:-}"

On native Windows where `python3` is unavailable:

python $SKILL_DIR/scripts/open_workbench.py --deck-dir "<deck_dir>" --agent-session-id "%HERMES_SESSION_KEY%"

If the user did not provide a deck path, let the helper auto-detect:

python3 $SKILL_DIR/scripts/open_workbench.py --agent-session-id "${HERMES_SESSION_KEY:-}"

Pass same-session bridge details when available:

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-session-id "${HERMES_SESSION_KEY:-}" \
  --agent-managed 1 \
  --agent-provider hermes \
  --agent-transport gateway \
  --webui-base-url "${HERMES_WEBUI_BASE_URL:-}" \
  --gateway-base-url "${HERMES_GATEWAY_BASE_URL:-}"

`--agent-transport` may be omitted: the helper auto-selects `gateway` when the Hermes Gateway endpoint and key resolve (environment or Hermes `.env` files), then `webui` / `acp` / `rest` when only those details exist. Explicit flags and `WORKBENCH_AGENT_TRANSPORT` always win. With no resolvable bridge the bottom chat stays read-only by design.

For non-Hermes interactive providers, pass structured bridge details instead of scraping CLI/TUI output:

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider openclaw \
  --agent-transport rest \
  --agent-base-url "${WORKBENCH_AGENT_BASE_URL:-}" \
  --agent-api-key "${WORKBENCH_AGENT_API_KEY:-}"

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider codex \
  --agent-transport acp \
  --acp-command "${WORKBENCH_ACP_COMMAND:-codex-acp}"

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider box-agent \
  --agent-transport acp \
  --acp-command "${WORKBENCH_ACP_COMMAND:-${BOX_AGENT_ACP_COMMAND:-box-agent-acp}}"

When this helper runs inside Box Agent, the exported `BOX_AGENT_PYTHON` or `BOX_AGENT_SKILL_TOOLS_ROOT` environment automatically selects `box-agent`, `acp`, and the installed `box-agent-acp` command. Explicit `WORKBENCH_AGENT_*` flags or environment variables still take precedence.

For WorkBuddy, pass `--agent-provider workbuddy` only as provider identity. Tell the user clearly that WorkBuddy currently has no supported API or ACP interface for the interactive workbench bridge, so the WebUI can show WorkBuddy status but cannot send bottom-chat modification turns back to WorkBuddy.

CLI Subcommands (direct launch fallback)

When bypassing `open_workbench.py` and invoking the workbench launcher directly, use subcommands:

node <launcher> start   --deck-dir "<path>" [--port 0] [--agent-managed]
node <launcher> status  --deck-dir "<path>"
node <launcher> stop    --deck-dir "<path>"

The old argument-only form (no subcommand) is **deprecated** — it will print a usage error.

**Restart pitfall:** `start` silently **reuses** an existing server instance for the same `deck-dir` (response contains `"reused": true`). If you updated the workbench code, you MUST run `stop` first, then `start` — otherwise the old process keeps serving stale code:

node <launcher> stop  --deck-dir "<path>"
node <launcher> start --deck-dir "<path>" --port 0

Bind Host

The workbench resolves its bind address from `--host` CLI flag → `WORKBENCH_HOST` env var → default `127.0.0.1`. When the user needs remote/LAN access, set `WORKBENCH_HOST=0.0.0.0`:

export WORKBENCH_HOST=0.0.0.0
node <launcher> start --deck-dir "<path>" --port 0

The response `url` field will then show the LAN IP instead of `127.0.0.1`.

Output Handling

Parse the single JSON line from stdout.

When `status == "ok"`, echo the returned `editor_url`, `public_url`, or `workbench.editorUrl` for exist