report-feedback

Files (5)

• SKILL.md
• apply-clicks.py · hooks/
• install-worker.py
• manifest.json
• report-feedback.py

SKILL.md (first lines)

# Report Feedback

When the user asks to **report a bug / issue / feature request / feedback about Sutando, AG2 Space or the desktop app** — e.g. "report this bug", "report this issue", "report an issue", "file a bug", "log this bug", "submit feedback", "I have a feature request", "tell the team this is broken" — use this skill to file it, whether the ask comes in a DM, in a room or by voice. "Report this on the PR" or "report this to <someone>" asks for a PR comment or a message, not a report.

**This is the only path that reaches the AG2 team.** The report goes skill → `/api/feedback` → Slack #product-feedback, a GitHub issue on sonichi/sutando and the master feedback DB. A message in a room or a DM, a hand-opened GitHub issue, or asking another agent (another Sutando included) to "add a row" or pass it on never gets there; do not do those instead of filing. After filing, reply with the reference id the script prints.

It posts to the cloud `/api/feedback` route (the same one the desktop "Report an issue" form uses, which mirrors into GitHub issues) and auto-attaches diagnostic context (platform + a tail of recent workspace logs), so you don't need to gather logs yourself.

This is the **single reporting path for all surfaces** — chat, Discord, Telegram, and voice (which reaches it by delegating the task to the core agent). There is intentionally no separate voice tool, to avoid duplicating the same capability.

## Usage

```bash
python3 skills/report-feedback/report-feedback.py \
  --title "<short one-line summary>" \
  [--body "<what happened, steps to reproduce, what was expected>"] \
  [--kind bug|feature|other] \
  [--severity low|medium|high|critical] \
  [--no-logs] [--auto]
```

- Ask the user for a short **title** and a **description** if they're not already clear from the conversation. Infer `kind` (default `bug`) and `severity` (default `medium`) from context.
- **Announce the log attachment before sending, then honor an opt-out.** Recent diagnostic logs are attached by default. Since there's no visible checkbox on voice/chat (unlike the desktop form), *say so first* — e.g. "I'll attach recent diagnostic logs to help debug, unless you'd rather I didn't." If the user declines, pass `--no-logs`. This makes it an informed opt-out rather than a silent default (especially important on voice, where the user can't see what's being sent). Log excerpts are redaction-scrubbed (Bearer tokens, `token=`/`api_key=`/`secret=` values, common key formats, and the home-dir username are masked) as a backstop, but announcing is still required.

## Ask first (`--ask`, or `askFirst` in the owner's prefs)

The owner's approval step for automatic reports. Instead of filing, the report is parked as a draft under
`<workspace>/state/feedback-drafts/<id>.json` and registered in the engine's HITL store (`src/hitl`) as a
`HumanRequirement`: the gateway bridge projects it as the owner's card — **File this bug report · File
without logs · Skip** — into its proactive room, and applies the click with the same stale-revision guard
every other card gets. Nothing is posted by this script, so it needs no gateway env.

```bash
# ask (also what --auto does when feedback-prefs.json has "askFirst": true):
python3 skills/report-feedback/report-feedback.py --auto --title "..." --body "..."
# after the owner answers (the click is durable in the HITL store): run the clicked choices
python3 skills/report-feedback/report-feedback.py --apply
python3 skills/report-feedback/report-feedback.py --drafts        # pending drafts, oldest first
python3 skills/report-feedback/report-feedback.py --decide <draft-id> file|file_no_logs|skip   # by hand
```

- The click is applied **automatically, in the turn it causes**: the requirement is created with
  `turn_on_action`, so the bridge records the click and then lets the same relay task through to the
  core (and re-forwards it if the relay redelivers the same click before that task was written, so a
  death in between cannot lose the turn); that task carries the header `hitl_click: true` and the card
  label as its body — it is a click
  already recorded, not an instruction: answer `[no-send]`, do not file by hand, and let the turn end —
  and the skill's `Stop` hook (`manifest.json` → `hooks/apply-clicks.py`, registered by
  `bash src/install-claude-hooks.sh` like every skill hook) runs `apply_clicks()` as that turn ends.
  `--apply` is the same routine by hand. It also registers any parked draft whose card was never created
  (a store write that failed at ask time exits 3 and keeps the draft).
- Filing is exactly-once by markers: before the post the draft becomes `<id>.posting`; a 2xx renames it
  to `<id>.filed`, the card is resolved, the receipt removed; a 4xx (the server refused, nothing written)
  renames it back to a draft. A 5xx proves nothing (the write may have committed), so like no answer at
  all (a transport error, a death mid-request) it leaves `<id>.posting`, and
  `--apply` **holds** it — never re-posted on a guess. A held draft is owner-visible: the answered card
  closes and a new card asks "Bug report: filed or not? — File it again / Skip"; its click runs through
  the same path (`file` re-posts on purpose, `skip` drops the in-flight draft). `--drafts` lists parked
  drafts; in-flight ones are visible to `list_drafts(ws, state="posting")`, and `--decide <id> file|skip`
  settles one by hand and closes its cards. The payload carries `context.idempotency_key = <draft id>`
  for a server-side check.
- `file` attaches logs only if `sendLogs` is on; `file_no_logs` never does; `skip` drops the draft.
  Logs are gathered only after the choice — the card carries the title only.
- The ask is the throttled event: dedupe and the daily cap are checked and **recorded** when the card
  is asked, and the off-switch applies to `--ask` as well as `--auto`.
- Draft ids are `fb_` + 10 lowercase hex; anything else is refused before any read or unlink.

## Automatic reports (`--auto`)

When **you** (not the user) determine that a bug or error is caused by Sutando itself or AG2 Space — engine services, bridges, the desktop app, AG2 Space connectivity, or the AG2 cloud — queue it with `--auto`. Never `--auto`-file problems in the user's own projects or code, third-party tools/sites/APIs, or expected failures (bad input, credentials the owner simply hasn't provided).

`--auto` enforces the owner's Settings toggles (read from `<workspace>/state/feedback-prefs.json`, written by the desktop app). When the file or a key is absent, both default OFF:

- **File automatic bug reports** — defaults **OFF** (absence of the prefs file is not consent). Off → the script prints `SKIPPED` and exits 3. Respect it — do not retry or route around it.
- **Send logs with bug reports** — defaults **OFF**, i.e. opt-in. Off → the log excerpt is omitted from every report (auto and manual), same as `--no-logs`.

Absence is not consent. An automatic report sends the owner's error context to the cloud, and the log excerpt adds incidental owner data — paths containing usernames, hostnames, workspace content. An owner who has never turned the toggles on files nothing automatically and ships no logs.

Auto reports are also deduped (an identical title within 24h) and rate-limited (5 per 24h) via `<workspace>/state/feedback-auto-reports.json`. A `SKIPPED` exit (3) is a normal outcome, not an error — just move on. Only after `OK: filed` (not `HELD`), tell the owner in one short sentence (e.g. "I've filed a bug report about this"); the Settings toggle is the consent surface, so don't ask permission first.

## Hold automatic reports while existing recovery runs

`--auto` first returns `HELD: incident fb_…`. The report stays locally in
`state/feedback-drafts/`; it sends nothing and creates no approval card yet.
An identical pending title reuses its incident ID and original deadline.
Manual reports without `--auto` remain immediate.

Use the returned incident ID to record the **existing** recovery lifecycle:

```bash
python3 skills/report-feedback/report-feedback.py --auto --title "Bridge disconnected" --body "Observed failure"
python3 skills/report-feedback/report-feedback.py --recovery fb_0123456789 started
# After the existing recovery finishes, record exactly one outcome:
python3 skills/report-feedback/report-feedback.py --recovery fb_0123456789 succeeded
# Or, only when recovery has definitively failed / exhausted its own timeout:
python3 skills/report-feedback/report-feedback.py --recovery fb_0123456789 failed
```

- Record `started` as soon as an existing recovery begins (or immediately after
  queuing if it is already running). **Do not start extra recovery to satisfy reporting.**
- Record `succeeded` only when the original failing operation is verified working.
  Restarting a process alone is insufficient. Success archives the local diagnostic
  draft as `.suppressed` and cancels any unsent approval card.
- Record `failed` only for the final outcome, not an intermediate failed retry.
  This immediately releases the report through the current preferences, daily cap,
  deduplication and ask-first flow. An already-failed recovery can be recorded
  immediately after queuing; no new attempt is required.
- If recovery never starts, the report becomes eligible one hour after queuing.
  If recovery is still running at that deadline, it remains held. The existing
  recovery controller/agent must report its final failure, including its own timeout.
  This skill never infers success or failure from unrelated health checks.
- Keep the incident ID with the task's recovery context across turns. Record outcomes
  for that incident only. Repeat detections do not extend the one-hour deadline.
- `--drafts` lists pending incidents and their recovery state. `--apply` evaluates
  deadlines and applies owner clicks. Reports carry `context.recovery` with the state,
  deadline and release reason. Automatic posting never claims owner approval.
- The auto-report off-switch is checked again at release; disabled queued reports
  are archived and do not return when the switch is re-enabled. Logs are collected
  only at filing, using current `sendLogs` and the queued `--no-logs` choice.

From sonichi/sutando, MIT.

More from sonichi/sutando