Papercuts

papercuts() adds the report_papercut tool to an Agent. Use it to capture small, non-blocking friction while the details are still available to the current Agent Invocation.

The Capability owns the reporting contract and provenance. Your application owns persistence, redaction, retention, deduplication, and triage.

Provide a report callback that accepts each papercut before the tool reports success.

The Capability always adds report_papercut. The tool accepts one trimmed message between 1 and 1000 characters and asks the Agent to describe what it was doing and what got in the way.

Each report includes an id, creation time, source, and available Agent, run, and trace provenance. The callback also receives the current Capability runtime context for application-specific routing.

Configure papercut reports

Persist the normalized papercut record and use context only when the sink needs invocation-specific information.

import { defineAgent } from 'vite-hub/agent'
import { papercuts } from 'vite-hub/agent/capabilities'

export default defineAgent({
  driver: { model },
  capabilities: [
    papercuts({
      async report({ papercut, context }) {
        await savePapercut({
          ...papercut,
          actorId: context.actor.id,
        })
      },
    }),
  ],
})

Do not serialize the runtime context wholesale. It is invocation-scoped and may contain request, actor, Workspace, or application values that do not belong in a papercut record; workspace and fs are absent on Agents without a Workspace.

Add the Capability CLI

Set cli: true to let agents and developers submit the same reports from a command. This adds the fixed papercuts report command without replacing report_papercut.

papercuts({
  cli: true,
  report: ({ papercut }) => savePapercut(papercut),
})

Run the command through the Agent Dev Loop.

pnpm vitehub agent dev --agent support --cli papercuts -- report "The retry hid the original error."

Successful command output is Papercut reported.

How reports work

ViteHub trims and validates the message, generates the record, and awaits report. The tool returns { reported: true, id } only after the sink accepts the report; callback errors fail the tool call instead of returning a false success.

The normalized record contains:

Attaching the Capability grants access to the developer-provided reporting sink, so papercuts() does not add an approval policy. It does not provide a when option. Attach the Capability only to Agent Definitions that report papercuts.

Requirements

papercuts({ report }) requires a report callback. Resolve the callback only after its destination accepts the record.

The tool description tells the Agent not to include secrets or customer data, but the sink still owns redaction and data handling appropriate to the application.

Driver support

Verify reports

Run one Agent Invocation that encounters a known problem and inspect the report_papercut call and normalized sink record. When cli is enabled, run papercuts report through the Agent Dev Loop and confirm the same sink receives a report with source: "cli".

Options

Related pages

• Agent Evals
• Custom capabilities