Skip to content

Problems

The Problems page (/problems, top level in the sidebar, outside Conversations & BI) shows what users reported through problem reports: the assistant offered a report after a server-side failure, or the user typed /problem, and approved what the dialog showed. This page covers reading and managing reports, and forwarding them out of DioscHub.

PermissionWhat it allowsHeld by
problems:readThe Problems page and GET /api/admin/problems…Viewer, Operator, Admin, Owner
problems:manageChange a problem’s status; the Sinks tab and the whole sinks API (reads included, because a sink URL often carries a token)Operator, Admin, Owner

The Data Protection Officer role holds neither: erasure, export and retention of stored reports are Data Privacy actions and need no license. After a downgrade the page and API turn off, but stored reports are still exported, erased and handled by retention.

A report is one user’s filing. A problem groups the reports that share one key: the assistant, the MCP server, the tool and the error category of the report’s first failed call, compared exactly. A report joins the open problem with its key, or opens one. A report with no failed call, or whose failed call lacks a part of the key, opens a problem of its own. A resolved or dismissed problem is never joined: the next report opens a new open problem. (Grouping of similar but not identical failures is not part of this release.)

The list shows, per problem:

ColumnMeaning
ProblemThe key as tool · server · category, then the title of the newest report
StatusOpen, Resolved or Dismissed
ReportsHow many reports the problem has had
ErasedHow many of them were erased
Last reportedWhen the newest report came in

Newest activity first, 50 per page. Three filters narrow it:

  • Status: all, open, resolved, dismissed.
  • Source of a report: any, Assistant offer (the assistant offered, the user approved) or User command (the user typed /problem).
  • Assistant’s assessment of a report: any, Defect, Not a defect (the user insisted on a report the assistant thought was not a fault of the application, such as a permission denial) or Unsure (the assistant gave none, or could not tell).

The two report filters keep a problem when at least one stored report matches; with both set, one report must match both. Reports that were erased no longer count for the filters.

Selecting a problem opens its reports, newest 50 first. Each shows its title, time, source, the assistant’s assessment, and whether it was anonymous. Open shows the full report: summary, steps, expected, actual, excerpt, page path, failed calls and, for a signed-in report, the reporter’s user id. Everything in a report is shown as text; nothing in it is rendered as markup or a link.

The session column reads:

  • a link to the conversation in the conversation explorer, when the license has Business Intelligence and your role holds conversations:read;
  • the plain session id otherwise;
  • Conversation no longer available when the conversation has been deleted by the retention window or by erasure. The report keeps the context its user agreed to share.

Reports that were erased are not listed; the header says how many (N reports erased) and the problem keeps its count.

With problems:manage the drilldown offers Resolve and Dismiss on an open problem and Reopen on a closed one. Reopening is refused (409) while another open problem holds the same key. A change to the status a problem already has does nothing and sends nothing.

Closing a problem starts a clock: 30 days after it was resolved or dismissed its reports are deleted. The problem row and its counts stay. Reports of an open problem are kept as long as it stays open, whether or not their conversation still exists. Set the period with the environment variable DIOSC_PROBLEM_REPORTS_PURGE_DAYS (a whole number of days, default 30, maximum 3650; anything else gives 30). The purge runs daily and is not an erasure, so it sends no report.erased event.

A sink forwards problem events to a URL you control: your tracker, a chat bridge, an automation. On the Problems page the Sinks tab (with problems:manage) lists them and lets you add, change, disable and delete them, and read each sink’s delivery log. There is no default sink: until you add one, nothing leaves DioscHub.

A sink has a name, a URL, a secret, the events it takes (at least one), an optional template and an enabled switch.

EventSent when
report.createdA report was stored. Carries the report.
problem.createdA report opened a new problem.
problem.status_changedAn admin changed a problem’s status. Carries change.from and change.to.
report.erasedA report was erased by user or session erasure. Carries only the report id and the reason.

report.erased is sent to every enabled sink that subscribes to it and that made at least one attempt to deliver that report’s report.created. A sink that never received the report is not told about its erasure. The tracker’s copy is the tracker’s: if the receiving system is part of your record keeping you must erase it there too, and the event is how you learn which report to erase.

Each delivery is an HTTP POST with Content-Type: application/json and these headers:

HeaderValue
User-AgentDioscHub-Webhooks/1
X-Diosc-EventThe event name
X-Diosc-DeliveryThe delivery id; the same on every retry, so use it to ignore duplicates
X-Diosc-TimestampUnix time in seconds of this attempt
X-Diosc-Signaturev1= followed by the hex HMAC-SHA256 of <timestamp>.<body>, keyed with the sink’s secret, over the exact bytes sent

The default body is { "event", "deliveryId", "occurredAt", "data" }, where data holds the report, problem, change and erasure objects that apply to the event. No body, default or templated, holds the reporter’s user id, the session id or any session field.

Recompute the signature from the raw request body, compare in constant time, and reject a timestamp that is too old to stop replays:

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret: string, headers: Headers, rawBody: string): boolean {
const timestamp = headers.get('x-diosc-timestamp') ?? '';
const given = headers.get('x-diosc-signature') ?? '';
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!(age <= 300)) return false; // older than 5 minutes, or not a number
const expected =
'v1=' + createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(given);
return a.length === b.length && timingSafeEqual(a, b);
}

Verify before you parse the body, and treat the contents as untrusted input. A report holds text drafted by the model and edited by a user. Escape it before you put it in a ticket, a chat message or a query.

To match a tracker’s format, give the sink a template: JSON text with {{field}} placeholders. DioscHub replaces each placeholder with the JSON literal of the value, so a string arrives with its quotes and a value can never break out of its place. Write placeholders outside quotes:

{
"title": {{report.title}},
"body": {{report.summary}},
"tool": {{problem.toolName}},
"labels": ["dioschub", {{report.assistantAssessment}}]
}
  • Fields: event, deliveryId, occurredAt, assistantId; report.id, report.title, report.summary, report.steps, report.expected, report.actual, report.pagePath, report.excerpt, report.failedCalls, report.source, report.assistantAssessment, report.createdAt; problem.id, problem.status, problem.serverName, problem.toolName, problem.errorCategory, problem.reportCount, problem.erasedReportCount, problem.firstReportedAt, problem.lastReportedAt; change.from, change.to; erasure.reason (user_erasure or session_erasure).
  • A field that does not apply to the event, or has no value, renders null. On report.erased only report.id of the report fields is filled.
  • There are no expressions, helpers or loops. A placeholder inside a JSON string, an unknown field name or any other {{ is refused when you save, and so is a template that does not render valid JSON for a sample of each event the sink takes. A template is at most 16 KB and a rendered body at most 256 KB.

Deliveries are queued and sent in the background, so a slow receiver never delays the user. Each attempt waits at most 10 seconds and re-reads the sink and the report, so a disabled, unsubscribed or deleted sink, or a report erased since, sends nothing.

OutcomeResult
2xxDelivered.
Network error, timeout, 408, 429, 5xxRetried with a growing delay (a few seconds, doubling to a cap of 10 minutes), at most 6 attempts, then failed.
Any other 4xx, or a 3xxFailed at once. A redirect is never followed.
URL refused by the policy, template no longer valid, body over 256 KB, secret unreadableFailed at once, without a request.

Each sink has a delivery log: event, status (pending, delivered, failed, cancelled), attempts, the receiver’s status code, a fixed reason such as Receiver reported a server error, and times. The log never holds the payload, the URL path, the response body or the secret. Rows are kept 30 days (a report.created row is kept while its report exists) and a pending delivery is never purged.

A sink URL goes through the same egress rules as MCP server URLs: it is checked when you save it and again, after a fresh DNS lookup, before every request. Link-local and cloud metadata addresses are always refused; private networks are refused unless you list them in EGRESS_TRUSTED_NETWORKS; plain http is only allowed to trusted targets (or everywhere with EGRESS_ALLOW_HTTP=true, which is the default outside production). The older MCP_TRUSTED_NETWORKS and MCP_ALLOW_HTTP names still work as a fallback. A refusal when saving is a 400; a refusal at send time is a failed delivery with the reason URL refused by the network policy. A URL may not carry a username or password, and is at most 2,048 characters. The page shows only a sink’s host, because the path or query often holds a token.

The secret is 16 to 256 characters. It is stored encrypted with a key derived from MCP_AUTH_MASTER_KEY, and is never returned by the API or written to a log or the audit trail. Without MCP_AUTH_MASTER_KEY on the hub, creating a sink or setting a secret is refused (WEBHOOK_SECRET_KEY_MISSING). To rotate it, edit the sink and enter a new secret; leaving the field empty keeps the stored one. The audit trail records that a sink was created, changed or deleted, but never its URL or template.

The Problems page uses these admin routes (all under /api, all licensed):

RoutePermissionPurpose
GET /admin/problemsproblems:readList; query status, assistantId, source, assistantAssessment, limit (1 to 200, default 50), offset
GET /admin/problems/:idproblems:readOne problem
GET /admin/problems/:id/reportsproblems:readA problem’s stored reports
GET /admin/problems/reports/:reportIdproblems:readOne report’s full content
PATCH /admin/problems/:id/statusproblems:manage (and problems:read)Body { "status": "open" | "resolved" | "dismissed" }
GET, POST /admin/problem-sinks; GET, PATCH, DELETE /admin/problem-sinks/:id; GET /admin/problem-sinks/:id/deliveriesproblems:manageSinks and their delivery log

Deleting a sink cancels its pending deliveries and removes its delivery rows. A request with an unknown field in the body is refused.

Problem reports add Prometheus metrics, listed in Observability: diosc_problem_reports_total, diosc_problems_open, diosc_problem_webhook_deliveries_total and diosc_problem_webhook_delivery_failures_total.