dsh-sentry

dsh-sentry

English | 繁體中文 | 简体中文 | 日本語

dsh-sentry is a free, open-source, read-only DeepSeek Harness plugin for the Sentry Web API. Every tool is an HTTP GET; the plugin never resolves, assigns, archives, or otherwise changes Sentry state.

Its main job is not proxying the API — it is trimming responses so an agent's context survives a real stacktrace. A raw events/latest/ payload is routinely 200KB–2MB. This plugin reduces it to the frames, source lines, and metadata that actually help debugging, and tells you in meta.trimmed what it had to leave out.

Tools

Tool	Purpose
sentry_list_projects	List up to 100 projects in the configured organization.
sentry_search_issues	Search issues with Sentry search syntax, in one project or the whole organization.
sentry_get_issue	Read one issue by numeric id or short id, without event bodies.
sentry_get_latest_event	Read an issue's latest event with a trimmed stacktrace.
sentry_get_event	Read one event by id within a project, with the same trimming.

All tools are read-only. Version 0.1 does not modify issues, create releases, or send events.

Requirements

• DeepSeek Harness with compatible @deepseek-ai/dsh-tools APIs
• Node.js 22.19 or newer in the 22.x line, or Node.js 24 or newer
• Bun 1.3.5 or newer when installing from GitHub source or developing locally
• A Sentry User Auth Token (sntryu_) with read access to the requested organization

Token scopes

Scope	Unlocks
org:read	/organizations/{org}/projects/, /organizations/{org}/issues/, /organizations/{org}/shortids/{short_id}/
project:read	/projects/{org}/{project}/issues/
event:read	/issues/{id}/, /issues/{id}/events/latest/, /projects/{org}/{project}/events/{event_id}/

Use a User Auth Token (sntryu_) with event:read, org:read, and project:read. The simplest safe one comes from sentry auth login --read-only, which requests exactly project:read, org:read, event:read, member:read, and team:read.

An Organization Auth Token (sntrys_) does not work: Sentry fixes its scope set to org:ci (Source Map Upload, Release Creation, Code Mappings) with no way to add read scopes, so every read path here returns HTTP 403. Verified against sentry.io on 2026-08-27 — see docs/live-verification.md.

Configuration

Field	Environment variable	Default	Notes
baseUrl	SENTRY_URL	https://sentry.io/	Site root URL. Use https://de.sentry.io/ for the EU region. A trailing /api/0 is stripped automatically.
token	SENTRY_AUTH_TOKEN	required	User auth token (sntryu_). Organization auth tokens are org:ci-only and are rejected with 403. Never returned or logged.
org	SENTRY_ORG	required	Organization slug. Fixed for the whole plugin instance.
locale	—	en	en, zh-TW, zh-CN, or ja. Selects the language of tool and parameter descriptions.
includeFrameVars	SENTRY_INCLUDE_FRAME_VARS	false	Keep stack frame local variables. Only the literal string true enables it. Agents cannot override this.
requestTimeoutMs	—	30000	Deadline for one whole tool call, including the extra request a short id costs. Range 1–300000.
maxResponseBytes	—	5242880	Hard cap on a single HTTP response body. Range 1–52428800.

Plugin configuration always wins over environment variables.

export SENTRY_AUTH_TOKEN='your-token'
export SENTRY_ORG='your-org'
# self-hosted or EU region only:
export SENTRY_URL='https://sentry.example.com'

Self-hosted and regions

• Self-hosted: point baseUrl at the site root, including a sub-path install such as https://example.com/sentry/.
• Sentry SaaS EU region: baseUrl must be https://de.sentry.io/. Using https://sentry.io/ for an EU organization surfaces as a 401 or 404, so both of those error messages repeat the region hint.
• Older self-hosted versions simply return fewer fields. The plugin treats every response field as optional and never fails because one is missing. Two known behavior differences: sort=recommended can be rejected (reported as UNSUPPORTED_BY_INSTANCE), and stats_period is limited to 24h and 14d.

What gets trimmed

Removed from every event, unconditionally:

• Request headers, cookies, environment, and body. The request URL keeps only origin and path — the query string is dropped whole, because OAuth callbacks and signed URLs carry secrets there.
• Stack frame local variables, unless includeFrameVars is on.
• mechanism.data, contexts.state, packages, modules, and _meta.
• user.email, user.ip_address, and user.username. Only user.id survives.
• Any tag whose key looks like a secret or direct PII (token, secret, password, passwd, api_key, auth, cookie, session, credential, private/access keys, JWT, DSN, signature, email, IP address, or username), plus every sentry:-prefixed internal tag.
• Frame fields that leak build paths, such as absPath.

Reduced rather than removed:

• Frames. Frames run outermost to innermost. When there are more than max_frames, the plugin prioritizes in-app frames, always includes the two innermost frames, fills from the tail when room remains, and never exceeds the cap. Output preserves the original order.
• Source context. Kept only for the three innermost in-app frames, at most 11 lines each, each line capped at 200 characters.
• Chained exceptions. At most the two innermost exception.values; max_frames applies to each stacktrace separately.
• Breadcrumbs. The last 20, messages capped at 200 characters.
• Strings. Exception values cap at 2000 characters; titles, messages, and culprits at 500.

If the result still exceeds the 200KB tool-result budget, the plugin degrades in fixed steps — source context, then breadcrumbs, then frames down to at most 10 without raising a lower caller cap. If administrator-enabled frame variables still make the result too large, they are removed as a final fallback. The last step is reported in meta.trimmed.degraded. Counters such as omittedFrames are always "original total minus what you received", never a running tally.

Localization

Tool and parameter descriptions follow locale. Tool names are always English and never change, because they are the agent's calling identifiers. Error messages are always English as well: they are stable diagnostic strings that tests and reviews compare against.

Security and error behavior

• Uses Authorization: Bearer ... and never returns or logs the token.
• Honors the DSH tool AbortSignal and a per-call deadline; a short id costs a second HTTP request but shares the same deadline.
• Converts HTTP 401, 403, 404, 429, and 5xx into safe structured errors that never carry a response body.
• One deliberate exception: on HTTP 400 from an issue search, the plugin reads at most 64KB of the body, takes only the structured detail or error string, drops it entirely if it contains the token or looks like it carries a secret, caps it at 200 characters, and appends it as Sentry said: .... Without that, an agent can only guess at a search-syntax error. When the body is HTML, unparseable, or filtered out, the message falls back to the static form — so INVALID_QUERY messages come in two shapes.
• Does not support disabling TLS verification or self-signed certificate bypass in v0.1.

Limitations (v0.1)

• No writes of any kind: no resolve, unresolve, archive, assign, merge, delete, release creation, or event ingestion.
• One organization per plugin instance; tools do not accept an organization parameter.
• No Seer AI, Performance, Discover, Metrics, Dashboards, Replay, Trace, or Span endpoints.
• No release, deploy, or issue-tag-distribution queries.
• stats_period is limited to 24h and 14d; custom start/end ranges are not supported.
• No automatic pagination. sentry_search_issues returns one page plus meta.nextCursor; sentry_list_projects accepts no cursor at all and reports meta.truncated instead.
• No local caching, no attachment or source map downloads, and no raw passthrough mode.

Development

This project uses Bun as its package manager and script runner; the published plugin runtime targets the Node.js versions listed above:

bun install --frozen-lockfile
bun run lint
bun run typecheck
bun run test --coverage
bun run build
bun pm pack

Tests use Vitest with mocked fetch and do not require a live Sentry instance. Coverage gates for lines, statements, functions, and branches are all set to at least 80%.

Live compatibility against Sentry SaaS and a self-hosted instance has not been recorded for this release yet. The checklist required before tagging v0.1.0 lives in docs/live-verification.md; run it against your own instance with:

bun run build
SENTRY_TOKEN=... SENTRY_ORG=... node scripts/live-verify.mjs

The script is read-only and exits 1 when credentials are missing.

License

MIT