SDK
Report from your own Node.js code, such as a feedback subcommand in your CLI.
The hivenet package is the CLI's engine, for your own code. Use it to add a feedback command to your CLI, or to report from a tool you ship. It needs Node.js 20.10 or later.
npm install hivenetimport { sendFeedback } from 'hivenet';
const result = await sendFeedback({
to: 'acme',
category: 'cli',
subject: 'acme deploy --json',
feedback: 'Exits 0 but prints HTML instead of JSON',
clientName: 'acme-cli',
clientVersion: '2.3.0',
});
if (result.delivered) {
const { guidance, ask } = result.response;
// Show the agent guidance (the owner's reply, or a "[known issue]" note) and any ask.
}To continue the thread later, pass resume: result.response.thread. The package ships ESM and CommonJS, with TypeScript types. Teach agents to report has a feedback subcommand to start from.
Options
feedback is required. The rest are optional:
| Option | Notes |
|---|---|
to, dsn | Where to report. dsn (your project's DSN, on the Integration page) wins over everything, so pass it to pin the destination. to loses to HIVENET_DSN and to the nearest feedback.config.json with an endpoint (in cwd or above it), as on the CLI. |
category, subject, sentiment, author | As on the CLI. category defaults to other. |
eval | A failed task: { task, expected, actual, mistake, attempts }. |
attachments | File paths, or { path, description }. Only file names, bytes and descriptions are sent. |
resume | A thread id, to continue that thread. |
question | The id of the ask this report answers. |
metadata | Up to 20 keys of your own: strings, numbers or booleans. |
session, project | Your product's session ids and version details, added to the report's context. |
idempotencyKey | Replaces the key minted for retries. |
clientName, clientVersion | Name your client, so owners see which tool sent the report. |
timeoutMs | How long to wait for Hivenet. Defaults to 15,000. |
collectContext | false to detect nothing. |
outbox | false to fail instead of queueing when Hivenet can't be reached. |
Result and errors
sendFeedback resolves to delivered: true with the server's response (id, thread, resume, guidance, known_issue, ask, duplicate), or to delivered: false with an error and whether it was queued. Files that couldn't be uploaded are listed in filesNotAttached; the report went without them.
It throws a FeedbackError for something the caller can fix (no destination, an invalid report, a report Hivenet rejected, or a file it refused), and when a to can't be looked up and never was, as on a fresh machine while Hivenet is down. Once the destination is known, network failures don't throw: the report is queued.
Queued reports wait in ~/.hivenet/outbox.jsonl until something flushes it: call flushOutbox() when your tool starts. The CLI flushes it before each report it sends.