Damper MCP referenca

Review artifacts

Review artifacts are the evidence an agent attaches to a roadmap task so a person can check the work without running it: API examples for changed endpoints, screenshots of changed pages and, optionally, diagrams of the logic or structure behind the change.

1. Attach evidence

   The agent calls add_api_example and add_screenshot while it works, and add_diagram when a flow, decision tree or set of relationships needs explaining.

2. Task goes to review

   request_review or the first complete_task moves the task to in_review, once the evidence the project requires is attached (or waived with a reason). Artifacts can still be added or replaced there.

3. Reviewer decides per artifact

   In the dashboard, a reviewer marks each artifact approved or changes requested, with one comment per artifact.

4. Agent reads feedback

   list_review_artifacts returns the verdicts and comments. The agent redoes what was flagged; a re-sent artifact goes back to pending.

Handing off to review

Agents should not leave reviewable work in in_progress. When there is a working slice, an opened pull request, attached evidence, or the session is about to end, the agent calls request_review with a summary of what to verify. It does not need user confirmation; complete_task still does.

• Lock release. The task moves to in_review and the lock is released, so it appears in the Review queue. The agent session closes; start_task reopens one.
• Partial stage. With stage: "partial", approving the review returns the task to in_progress for the next slice instead of marking it done, and the queue shows a "Partial stage" label. Sending it back needs a comment, as always.
• No early finish. While a stage review is pending, complete_task is rejected; wait for the decision and resume with start_task.
• Nudges. link_pr, add_screenshot, add_api_example and add_commit remind the agent about request_review while the task is in progress. get_project_context and list_tasks list the calling key's in-progress tasks that look ready (idle 12 hours or more with a linked PR, attached evidence, or all subtasks done), and the Review page shows them under "Possibly ready" with a "Move to review" button.

Waiting for review feedback

After request_review or complete_task lands the task in in_review, an agent with the Damper CLI installed can run damper review wait <taskId> as a background command. It exits 10 when the reviewer asks for changes (the feedback is printed; resume with start_task), 0 when approved (for a partial stage this means: continue the remaining work, then request review again), 2 when it timed out — the watch stays registered, so do not re-arm it more than once — and 1 on an error such as an API key that cannot see the task (details on stderr). When the agent resumes, start_task and get_task show a “Reviewer feedback” block with the round, the overall comment and each artifact marked changes requested.

• damper review wait <taskId> — block until one task is decided.
• damper review watch — long-running watcher that resumes agents when decisions arrive.
• damper review inbox and damper review status — undelivered decisions and watcher state.
• damper review service install — keep the watcher running as a background service.

Pass previewUrl to request_review or complete_task when the change is running somewhere the reviewer can open. The Review page shows an “Open preview” link; the URL is never part of public roadmap output.

Verdicts are feedback on the evidence. They do not change the task's status and do not gate completion. Note that review_task is something else: a self-assessment the agent writes about its own session, not a human review.

Review evidence policy

Each project sets what agents are asked to attach. Every kind (apiExamples, screenshots, diagrams) has a base level (off, suggested or required) for any change that triggers it, plus optional rules that raise or lower the level for specific surfaces, change kinds or risk domains. Read and change the policy with get_project_settings and update_project_settings (reviewEvidencePolicy, a partial update), or in the dashboard under project settings.

How levels resolve

1. If the change has none of the kind’s trigger change kinds, the kind is off.
2. Otherwise it starts at the base level.
3. A rule looser than the base lowers it only when the whole change is inside the rule (all of its surfaces, triggering change kinds and risk domains are listed), so a change that also touches something else keeps the stricter level.
4. A rule stricter than the base raises it when the change touches any value the rule lists. The strictest matching rule wins.

Examples: API examples suggested with apiExamplesRules: [{ "level": "required", "riskDomains": ["public_api"] }] are required for public API changes and suggested elsewhere. Diagrams suggested with a required rule for ["billing", "checkout"] are required there and still prompted for everywhere else. Screenshots required with { "level": "suggested", "appliesTo": ["ios"] } are only suggested for an iOS-only change.

get_completion_checklist with appliesTo / changeKinds / riskDomains returns reviewEvidence.forScope: the level and reason for each kind, computed exactly as the hand-off gate, prepare_work and prepare_completion do. Without a scope it returns the policy itself.

A suggested gap returns a warning. A required gap blocks every hand-off into review until the evidence is attached or evidenceNotApplicable explains why it is not:

• Entering review. request_review (partial stages only warn unless partialStageEvidence is block), complete_task, and a status change to in_review from the dashboard, PATCH /api/projects/:id/roadmap/:itemId or an AI task link all run the check. The scope is what the call declares plus what prepare_completion or an earlier hand-off recorded; prepare_work’s expected paths count per plannedScope.
• Approving. Approving a complete-stage review, moving the item from in_review to done, or finalizing with complete_task re-checks the evidence recorded at hand-off against what is attached now. A waiver given at hand-off carries over; the reviewer can also pass evidenceNotApplicable.
• Each round. After a reviewer decision (changes requested, or a partial stage approved), only artifacts attached or replaced since that decision count. A reviewer marking an existing artifact does not make it new. Declare the new round’s scope with touchedPaths / checklistScope.
• Existing reviews. Items that entered review before the check existed are approved as before.

The error is the same on every surface: HTTP 400 with code: "review_evidence_missing", evidenceGaps (each with kind, mode, message, and the changeKinds, appliesTo and riskDomains that call for it), evidenceSince and waiverField: "evidenceNotApplicable". Waivers are recorded on the task timeline.

HTTP routes

Agents without MCP can use the same operations over HTTP with Authorization: Bearer dmp_....

Upload a screenshot with curl

Request an upload URL, then PUT the image to it. The image never passes through the agent's context.

# 1. create the screenshot and get a single-use upload URL
curl -X POST https://api.usedamper.com/api/agent/tasks/TASK_ID/artifacts/screenshots \
  -H "Authorization: Bearer dmp_..." \
  -H "Content-Type: application/json" \
  -d '{"page": "Invoices list", "state": "empty", "requestUpload": true}'

# 2. PUT the bytes to the returned upload.url (no key needed, expires in 30 minutes)
curl -X PUT -H "Content-Type: image/png" \
  --data-binary @invoices-list--empty.png \
  "https://api.usedamper.com/api/agent/artifact-uploads/UPLOAD_TOKEN"

CLI

The Damper CLI does both steps for a whole folder of images. It needs DAMPER_API_KEY set to a project key.

damper artifacts upload --task TASK_ID [--manifest file.json] [image|dir ...]

Flags: --theme, --locale, --viewport and --change (added, changed or removed) set defaults for every screenshot; --dry-run lists what would be uploaded without sending anything. Without a manifest, name files page--state.png: invoices-list--empty.png becomes page “invoices list”, state “empty”. A manifest gives full control:

{
  "screenshots": [
    {
      "file": "shots/invoices-empty.png",
      "beforeFile": "shots/invoices-empty-before.png",
      "page": "Invoices list",
      "state": "empty",
      "theme": "light",
      "viewport": "desktop",
      "change": "changed"
    }
  ],
  "apiExamples": [
    {
      "method": "GET",
      "path": "/invoices?status=paid",
      "response": { "status": 200, "body": { "data": [] } }
    }
  ]
}

Other screenshot fields: route, locale, title, description and key. File paths are relative to the manifest. Each entry in apiExamples takes the same fields as add_api_example.