Web Choices server and submission runbook

Oracle-generated strict JSON choices served through a skill-local Svelte/mdsvex app, with Tailscale Funnel, persistent drafts/submissions, blocking wait-and-resume, verification, and recovery safeguards.

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 .svx route 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 build succeeds in ~/.agents/skills/web-choices.
  • The current page is served from compiled Svelte/mdsvex output.
  • The public or local API returns the expected jobId and 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_DIR first, 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 tmux session 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.

Source references