Use this for agent-generated option lists that the user should review in a clean, polished, interactive browser experience or on a phone.
The durable implementation lives in this skill directory:
~/.agents/skills/web-choices
Agents must launch the skill-local CLI from any project and must store runtime state in a caller-selected HITL_OUT_DIR, usually $PWD/.hitl-choice.
Non-Negotiables
- The browser UI must be compiled from Svelte and mdsvex sources in this skill.
- At least one
.svxroute or template must be part of the served choice experience. - A plain generated HTML form, static DOM script, or one-off Markdown page is not an acceptable implementation.
- Oracle-generated choices remain strict JSON data. Do not compile Oracle/user option strings as Svelte or mdsvex source.
current-job.json, drafts, and submissions remain the durable source of truth.- The app must run from any project. Do not hardcode
script-kit-gpui. - Do not overwrite an active current job without inspecting status and requiring explicit replacement.
- Keep the HITL server alive in
tmux; do not stop it after sending the URL. - Wait for the saved submission before continuing. The local wait defaults to no timeout.
Generate Choices With Oracle
For repo-aware lists, use $oracle-packx and include process docs plus relevant source/tests. For large context, use Oracle browser attachments rather than inline-only prompts.
Oracle generation is blocking. After starting the Oracle choice-list request, do not draft choices locally, publish a partial job, or continue until Oracle has completed and the local Oracle response has been read.
Ask Oracle for a strict JSON job:
{
"jobId": "short-stable-id",
"title": "Human-readable title",
"description": "What the user is choosing",
"createdAt": "ISO timestamp",
"options": [
{
"id": "stable-option-id",
"title": "Short option title",
"description": "Concrete choice text",
"tags": ["optional"],
"surface": "optional area",
"goal": "optional goal",
"risk": "optional risk",
"suggestedProofCommands": ["optional command"],
"expectedEvidence": {
"pass": "optional pass signal",
"fail": "optional fail signal"
}
}
]
}
If a selected option later fails verification, ask Oracle again with a Prior-State Ledger and Forward Progress Gate describing the failure, selected option, logs, and what has already been tried.
Build And Serve The mdsvex Choice Experience
The skill-local app is a Bun + Vite + Svelte + mdsvex app. mdsvex owns the page/template shell; Svelte components own filters, cards, selection state, feedback fields, save status, and submission controls. Runtime data remains JSON-driven.
From any project:
export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices"
export HITL_OUT_DIR="$PWD/.hitl-choice"
export HITL_HOST="127.0.0.1"
export HITL_PORT="8877"
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server \
--out-dir "$HITL_OUT_DIR" \
--host "$HITL_HOST" \
--port "$HITL_PORT" \
--tmux
The server writes or reuses $HITL_OUT_DIR/.token. Read the token from that file or from the server status.
Confirm the server is alive:
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status \
--out-dir "$HITL_OUT_DIR" \
--url "http://127.0.0.1:$HITL_PORT" \
--token-file "$HITL_OUT_DIR/.token"
Push the Oracle-generated job:
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push /path/to/job.json \
--url "http://127.0.0.1:$HITL_PORT" \
--token-file "$HITL_OUT_DIR/.token"
Use --replace only after inspecting active job status and confirming replacement is safe.
Start and verify Tailscale Funnel by default:
tailscale funnel --bg --yes "$HITL_PORT"
tailscale funnel status
curl -s "https://<your-tailnet-host>.ts.net/api/jobs/current?token=$(cat "$HITL_OUT_DIR/.token")"
Give the user the public URL only after the public API returns the expected jobId and option count:
https://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN>
Tell the user the server is staying open, drafts are saved server-side, and you are waiting for their submission.
Wait And Resume
Wait locally without a timeout unless the user asks otherwise:
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait \
--job "<jobId>" \
--out-dir "$HITL_OUT_DIR"
Persisted sources of truth:
$HITL_OUT_DIR/current-job.json$HITL_OUT_DIR/drafts/$HITL_OUT_DIR/submissions.jsonl$HITL_OUT_DIR/submissions/<submissionId>.json
After submission, report the submissionId, selected count, selected option IDs/titles, per-option feedback, overall feedback, and saved file path. Continue from saved JSON, not memory.
Verification
Before giving the user the URL, verify:
bun run buildsucceeds in~/.agents/skills/web-choices.- The current page is served from compiled Svelte/mdsvex output.
- The public or local API returns the expected
jobIdand option count. - Desktop and phone-width rendering are usable.
- Draft saving and final submit persist JSON under
HITL_OUT_DIR.
Failure Prevention
- If the tunnel fails, keep the same server/job/token when possible and restart Funnel; do not regenerate choices unless asked.
- If the server dies, inspect
HITL_OUT_DIRfirst, restart with the same token, and verify drafts/submissions still exist. - If the user says they submitted but wait has not returned, check
submissions.jsonl, per-submission files, server logs, and/api/jobs/<jobId>/submissions/status?token=<token>. - If laptop sleep or network loss is possible, say the server is durable while the machine and Tailscale are online; leave the
tmuxsession running. - Do not expose sensitive choices over a public Funnel URL without user approval. The token gates access but is not full authentication.
Operational boundaries
- The bundle includes the skill instructions, not the complete runnable Svelte/mdsvex app. Install or locate the implementation before using its CLI paths. Funnel exposes the service publicly; token-bearing links are not full authentication.