Preface

In DSH’s “everything is a plugin” mode, plugins write context such as prompt sections and tool schemas to every request. For agent developers and plugin maintainers, the question isn’t just “what is installed,” but also: which layer these contents come from, why they exist, who they affect if disabled, and how many tokens they consume per request.

dsh-xray is a context visibility tool for DeepSeek Harness. It separates actual loaded content, composition relationships, and context costs, providing verifiable data.

What is this

dsh-xray is the alloevil/dsh-xray project, licensed under MIT, with package.json version 0.10.2.

Its one-sentence positioning is: X-ray for your DeepSeek Harness — see what’s actually loaded, why, and what it costs you.

It provides three types of entry points:

  1. Adding an X-Ray tab in the running harness, alongside Chat and Trajectory.
  2. A standalone /xray page.
  3. CLI commands.

The main issues it focuses on are LLM context-cost observability: per-plugin token attribution, prompt-section and tool-schema pricing, skill catalog tax, and dependency cascades.

Core Features

Context Cost Attribution

dsh-xray breaks down context overhead in every request by plugin:

  • Per-plugin rollup: prompt sections, tool schemas, tokens, share, sorted by cost.
  • Entry inspection: Returns live text for a specific entry via /xray/api/entry, along with a chars/tokens ruler; the text is calculated per request and not persisted to disk.
  • Skill cost view: Performs cost calculation for each skill catalog line and skill body; it is responsible only for calculation, while switch management still belongs to skill managers in the ecosystem.
  • Per-request ledger: Splits system, tool schemas, history, and tool results for a single LLM request; tool results are aggregated by tool, showing Δprev growth and prefix-stability markers.

Plugin Composition Diagnosis

dsh-xray’s CLI provides the following commands:

  • attribute: View which layer introduced each row, and who patched it subsequently.
  • conflicts: View which fields have multiple writers, and who wins in the end.
  • diff: Compare declared static layers with the actual dump-config tree.
  • snapshot: Export a content-addressed lockfile of the current effective composition.
  • deps [svc]: View the service dependency graph, including providers, consumers, and disable-cascade.
  • health: View plugin lifecycle health, including failed fibers, pending injects, and transitions.
  • cost: View context costs, including estimated tokens for prompt sections and tool schemas.
  • shadow: View services provided by multiple plugins with the same name.
  • audit: Perform a static scan of out-of-tree plugins to check for sensitive touchpoints.

Among them, attribute, conflicts, and snapshot are completely static and can be used even if DSH fails to start.

Agent Tools

After mounting, dsh-xray registers the xray_composition agent tool, supporting the following views:

summary
deps
health
cost
shadow

Installation and Enablement

In the currently scraped materials, the Install section of the README is truncated and does not provide official installation commands; this article does not stitch together installation steps.

Verified package information is as follows:

  • Package name: dsh-xray
  • Version: 0.10.2
  • License: MIT
  • Main entry: lib/index.js
  • Bin: dsh-xray
  • Dependencies: yaml

Verified DSH enable metadata is as follows:

  • dsh.bundle.patch: ./cordis.patch.yml
  • Client platform: web
  • Inject modules:
  • @deepseek-ai/dsh-client-runtime
  • @deepseek-ai/dsh-client-locale
  • @deepseek-ai/dsh-client-ui-slots
  • @deepseek-ai/dsh-client-ui-conversation

Typical Usage

The following commands come from verified usage examples:

npx dsh-xray attribute   # which layer introduced each row, and who patched it since
npx dsh-xray conflicts   # rows whose fields have multiple writers, and who wins
npx dsh-xray diff        # declared (static layers) vs actual (dump-config) tree
npx dsh-xray snapshot    # content-addressed lockfile of the effective composition
npx dsh-xray deps [svc]  # service dependency graph: providers, consumers, disable-cascade
npx dsh-xray health      # plugin lifecycle health: failed fibers, pending injects, transitions
npx dsh-xray cost        # context cost: prompt sections + tool schemas, estimated tokens
npx dsh-xray shadow      # services provided by multiple plugins
npx dsh-xray audit       # static scan of out-of-tree plugins for sensitive touchpoints

All CLI commands support:

--profile <name>
--json

where --profile defaults to web. diff and health exit with code 1 when there is drift or unhealthiness, making them suitable for CI.

In a running harness, you can use the X-Ray tab, the standalone /xray page, or the CLI. To view live text for a specific entry, you can access:

/xray/api/entry

This endpoint returns the entry’s real-time text, along with a chars/tokens ruler.

Security Boundaries

dsh-xray’s security posture is read-only, it does not execute:

  1. !!js expressions in patch files are only parsed as opaque markers and not evaluated.
  2. The CLI does not execute plugin code; audit is a pattern scan of source code text.
  3. Mounted plugins only write to $DSH_HOME/xray/.
  4. Entry text is returned in real-time and not persisted.
  5. The entry endpoint only returns composition-layer text and does not return session messages.

Use Cases and Notes

dsh-xray is suitable for the following scenarios:

  • Troubleshooting token overhead caused by multiple plugins writing to context in DSH.
  • Determining why a specific plugin appears in the effective composition.
  • Viewing which services are affected by disabling a plugin.
  • Comparing declared configuration with actual dump-config results.
  • Checking composition drift or plugin health status in CI.
  • Allowing an agent to view its own plugin composition via xray_composition.

Points to note:

  • Plugins run with the permissions of the current dsh process; you should check the source code and license before installing.
  • audit is a static scan, not a verification of the dynamic execution environment.
  • The current materials do not provide complete installation commands; the specific installation method should follow the GitHub repository instructions.

Conclusion

The value of dsh-xray lies in transforming “what is actually loaded, why it is loaded, and how much it costs per request” from empirical judgment into verifiable data. It can be used as an X-Ray tab in a running harness, or as a CLI for static diagnostics and CI checks.

Repository address: https://github.com/alloevil/dsh-xray