mutagent reports, findings, triage

When Helix evaluates or diagnoses an agent, it writes a report: what was checked, what failed, and why. These commands keep those reports in your workspace, so your team can read them, mark them reviewed, and follow each failure until it is fixed.

A report is one run’s result: an evaluation, a diagnosis, a discovery run, or a person’s review.
A finding is one failing or undecided criterion from an evaluation report. Findings are created for you when you store an evaluation report.
A triage item is a problem you file about an agent, skill or workflow, for example after a customer complaint.

Before you start: install the CLI, sign in (MUTAGENT_API_KEY=<key> mutagent login --json for a coding agent), and select the workspace with mutagent workspaces use <workspace-name>. To push a report, Helix must be installed (mutagent install), because helix-cli, which ships with it, publishes the report first. Reads (list, show) need no confirmation. Every write (push --replace, review, retract, set-status, triage file) changes shared workspace data: a coding agent confirms with the person before it runs one.

A worked example

helix-cli report publish runs/42/report.html runs/42/report.client.html
mutagent reports push runs/42 --kind evaluator
mutagent findings list --status open
mutagent reports review <report-id>
mutagent findings set-status <finding-id> resolved

helix-cli report publish publishes the report Helix rendered. reports push stores the evaluation report from the run folder runs/42. Storing it creates a finding for every criterion that failed or could not be decided.
findings list shows the open findings.
After someone has read the report, reports review marks it reviewed.
When the fix is in, findings set-status … resolved closes the finding.

mutagent reports push

Store a report in the workspace.

mutagent reports push <run-folder-or-report-file> --kind <kind> --json

Argument or flag	What it does
`<run-folder-or-report-file>`	The run folder (with `render-input.json` and one `*.client.html`), or the published HTML file.
`--kind <kind>`	Required. `evaluator`, `diagnostics`, `discovery`, or `hitl` (a person’s review of a run).
`--subject <id>`	The agent, skill or workflow the report is about.
`--run-id <id>`	The run that produced it. The default is the run ID in the report. Not with `--kind hitl`.
`--session-ref <ref>`	The Helix session reference.
`--title <text>`	The title. The default is the report’s own title.
`--render-input <file>`	The render-input JSON. The default is `render-input.json` next to the HTML.
`--replace`	Replace the report already stored for this run and kind. It keeps its ID and is marked unreviewed. Not with `--kind hitl`.

Only reports published with helix-cli report publish are accepted. Publishing removes personal data from the report. A file that was not published is refused with REPORT_NOT_PUBLISHED (exit 1), and nothing is sent. Run the publish command the error names; do not edit the HTML by hand. A report published by an older helix-cli must be published again. Success: exit code 0. With --json: { success, created, replaced, report, _links, _directive }. Pushing the same run and kind twice stores nothing new: the second push returns created: false and replaced: false with the first report. That is a success, so a script can retry safely. A hitl report has no run ID, so every hitl push stores a new report.

mutagent reports list, show, review, retract

mutagent reports list --kind evaluator --subject support-bot
mutagent reports show <report-id> --html report.html
mutagent reports review <report-id>
mutagent reports retract <report-id> --force

Command	What it does
`reports list`	The workspace’s reports, newest first. Filter with `--subject`, `--kind`, `--run-id` or `--session-ref`; page with `--cursor`.
`reports show <id>`	One report. `--html <file>` saves the report page so you can open it in a browser.
`reports review <id>`	Mark the report reviewed. `--undo` marks it unreviewed.
`reports retract <id> --force`	Delete the report, its findings and its page. It never asks: without `--force` (or `--yes`) it refuses with `CONFIRMATION_REQUIRED`. Retracting a report that is already gone succeeds.

With --json, reports list returns { reports, count, nextCursor }; nextCursor is null on the last page. An unknown report ID is REPORT_NOT_FOUND (exit 1).

mutagent findings

mutagent findings list --status open --subject support-bot
mutagent findings set-status <finding-id> resolved

Command	What it does
`findings list`	Findings, newest first. Filter with `--status` (`open`, `in-diagnostics`, `resolved`), `--subject`, `--run-id` or `--report`.
`findings set-status <id> <open\|resolved>`	Close a finding, or open it again. Setting the status it already has succeeds and changes nothing.

With --json, findings list returns { findings, count } in one page. set-status is refused (exit 1) with STATUS_SET_BY_ROUTING if you ask for in-diagnostics, ILLEGAL_STATUS_TRANSITION, STATUS_CHANGED (someone changed it first: list it again before you retry) or FINDING_NOT_FOUND. Each finding shows the criterion that failed, its severity, whether it blocks a release (gating), and the report it came from.

mutagent triage

File a problem about an agent, skill or workflow, then follow it to a fix.

mutagent triage file --subject support-bot \
  --title "Quotes the wrong refund window" \
  --body "Told a customer 60 days; the policy is 30."

The command first prints exactly what it will send: the workspace, every field and the full text. In a terminal it then asks, and sends only if you say yes. Under --json, in CI or in a pipe, it sends nothing until you run it again with --yes. For a coding agent:

Run it with --json and without --yes. It returns sent: false, consentRequired: true, a preview and next, and exits 0.
Show preview to the person and ask whether to file it.
Only on a yes, run next[0] (the same command with --yes). It returns sent: true and the item.

Flag	What it does
`--subject <id>`	Required. The agent, skill or workflow the problem is about.
`--title <text>`	Required. One line.
`--body <text\|@file>`	Required. What happened, or `@path` to read it from a file.
`--severity <level>`	`CRIT`, `HIGH`, `MED` or `LOW`.
`--subject-kind <kind>`	`agent`, `skill`, `workflow` or `multi-agent-system`.
`--repo <owner/name>`	The GitHub repository the subject lives in.
`--source <source>`	Who is filing: `chat` (the default), `trace-score`, `external` or `mention`.
`-y, --yes`	Send without asking. Use it only after you have read the preview.

Command	What it does
`triage list`	Triage items, newest first. Filter with `--status` and `--subject`.
`triage show <id>`	One item, with its full text.
`triage set-status <id> <open\|resolved>`	Close an item, or open it again. It is refused like `findings set-status`; an unknown ID is `TRIAGE_NOT_FOUND`.

There is no delete for triage items: an item is resolved, not removed.

If it fails

Exit code or error	Fix
`3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`)	Sign in, then `mutagent workspaces use <workspace-name>`.
`2` (`AUTH_EXPIRED`, `INVALID_API_KEY`)	Sign in again, or set a valid `MUTAGENT_API_KEY`.
`REPORT_NOT_PUBLISHED` (exit 1)	Run the `helix-cli report publish` command in `suggestedAction`, then push again.
`CONFIRMATION_REQUIRED` (exit 1)	`retract` needs `--force`. Confirm with the person first.
`STATUS_CHANGED` (exit 1)	Someone changed the status first. Read it again and ask before you retry.

On any other error, run the command in suggestedAction once; do not retry blind. See CLI errors.

CLI

Account

Workspace

Helix

Setup

mutagent reports, findings, triage

A worked example

mutagent reports push

mutagent reports list, show, review, retract

mutagent findings

mutagent triage

If it fails

​A worked example

​mutagent reports push

​mutagent reports list, show, review, retract

​mutagent findings

​mutagent triage

​If it fails

A worked example

mutagent reports push

mutagent reports list, show, review, retract

mutagent findings

mutagent triage

If it fails