dsh-runtime-nutrition-label

English | 中文

Evidence-backed runtime nutrition labels for DeepSeek Harness tool namespaces and plugin identities.

This is a community-maintained plugin published from biubiukam/dsh-runtime-nutrition-label. It is not an official DeepSeek AI package or endorsement.

What it provides

This plugin observes the DSH tool and filesystem event seams and publishes a bounded JSON snapshot for each configured plugin identity. A label separates author or deployer declarations from facts observed during the current process window.

• Declared capabilities: network, credentials, subprocess, persistence, and expected domains.
• Observed tool metrics: schema bytes, calls, successes, failures, duration statistics, argument/result byte totals, and configured side-effect classifications.
• Observed filesystem metrics: reads, writes, unique target count, and privacy-controlled path samples.
• Observed network destinations: hostnames found in HTTP(S) URL arguments, never complete URLs.
• Bounded evidence records with declared, observed, and inferred provenance.

The first release deliberately does not compress these fields into a scalar grade. Declarations, runtime observations, and deployment policy have different evidence quality and must remain distinguishable.

Install with DSH

dsh plugin --profile web add dsh-runtime-nutrition-label
dsh --profile web

The package declares a dsh.bundle patch, so dsh plugin installs it into the selected profile, appends it to dsh.profile.bundles, and automatically mounts both the ctx.runtimeNutritionLabels service and /nutrition-label command. The default configuration attributes visible tools to the reserved unattributed label until the profile supplies explicit mappings.

For a direct Cordis composition that does not use DSH profiles, install the package as an ordinary dependency:

pnpm add dsh-runtime-nutrition-label

The package has a normal peer dependency on @deepseek-ai/cordis. DSH runtime packages are listed under the package-specific dsh.runtimePeers metadata because the current public DSH RC dependency graph does not publish every transitive type package required for a clean standalone install. A DSH deployment must provide compatible @deepseek-ai/dsh-tools, @deepseek-ai/dsh-fs, @deepseek-ai/dsh-commands, @deepseek-ai/dsh-invariants, @deepseek-ai/dsh-session, and @deepseek-ai/dsh-session-projection implementations when the structured Web report path is enabled. The metadata can move back to ordinary peer dependencies when that public graph is complete.

Composition

The shipped cordis.patch.yml inserts the service and command rows. Attribution is explicit: this plugin does not infer Cordis fiber ownership from an opaque runtime object, so a profile configures exact tool names or prefixes by overriding the runtime-nutrition-label row in its own cordis.patch.yml:

- id: runtime-nutrition-label
  config:
    plugins:
      - id: mcp-github
        displayName: GitHub MCP
        tools:
          prefixes:
            - mcp__github__
        declared:
          network: true
          credentials: true
          domains:
            - api.github.com
        effects:
          - prefixes:
              - mcp__github__create_
              - mcp__github__merge_
            effect: write

The bundle enables the separate human command consumer by default. Disable only that row when the profile should collect labels without exposing /nutrition-label [plugin-id]:

- id: runtime-nutrition-label-command
  disabled: true

See examples/cordis.patch.yml for a complete profile override.

Configuration

plugins[].tools requires at least one exact name or prefix. Exact tool ownership must be unique, and prefix ranges may not overlap. The reserved label id unattributed is used for unmatched tools when includeUnattributed is enabled.

effects are ordered rules scoped to one configured plugin. Exact names take precedence over prefixes, and an unmatched tool has effect unknown. The effect is a configured classification, not proof that a provider performed the operation.

evidenceLimit, callSampleLimit, fileSampleLimit, domainSampleLimit, argumentScanMaxDepth, and argumentScanMaxNodes are validated positive or non-negative safe integers at load time. callSampleLimit caps the current-window tool trace; pathDisplay accepts omit, basename, or full; omit is the recommended default for shared reports.

Snapshot contract

The service exposes:

ctx.runtimeNutritionLabels.snapshot()
ctx.runtimeNutritionLabels.snapshot('mcp-github')
ctx.runtimeNutritionLabels.snapshotFor(agent)
ctx.runtimeNutritionLabels.snapshotFor(agent, 'mcp-github')
ctx.runtimeNutritionLabels.reset()
ctx.runtimeNutritionLabels.ownerOfTool('mcp__github__create_issue')

Agent-scoped snapshots use the exact DSH agent scope for schema visibility and runtime events. The /nutrition-label command uses the receiving agent automatically, so tools mounted only by a Web preset appear in that agent's report instead of the root report.

Snapshots are deeply frozen and have schemaVersion: 1. They include an ISO timestamp, a monotonic in-process revision, configured declarations, observed aggregates, and bounded evidence records. The service never stores raw tool arguments, raw tool results, file contents, credential values, or complete URLs.

Evidence semantics

Declared

declared fields come from plugin authors or deployment configuration. They describe intended or possible capabilities and remain present even when the current process has not exercised them.

Observed

observed fields come from DSH event payloads or the visible tool schema registry. Filesystem writes count only after a write or edit intent is followed by an authoritative fs/observed event.

Inferred

inferred evidence records explain classifications derived from explicit configuration, such as a tool being marked write by an effect rule. Inference is never presented as an observed provider fact.

Privacy model

• Tool and result sizes are retained as byte counts, not payloads.
• URL scanning retains hostnames only and ignores URL paths, queries, fragments, and credentials.
• File samples are optional and can be omitted entirely; the collector does not read file contents.
• Evidence records are capped per label and are intended for local diagnostics, not an audit archive.
• Credential declarations contain booleans and expected reference metadata only; secret values never enter the snapshot.

Model Experience

This package does not add a model-facing tool or prompt section. The optional /nutrition-label command is dispatched by a human command consumer and does not change model history.

Human command report

/nutrition-label returns a summary-first report for the receiving agent. Text-only adapters receive a Unicode line-drawn table, while the Web client can render the same Host-produced report as real HTML tables through the keyed command slot. It starts with the report scope, command id, snapshot revision, generation time, and each label's observation window. Each label then shows:

• a status block explaining whether tools are loaded, whether any calls were observed in the window, and whether plugin attribution is configured;
• a runtime summary for visible tools, schema size, calls, successes, failures, filesystem activity, and observed network domains;
• a capability table that keeps author or deployment declarations separate from runtime observations. No runtime evidence means this collector did not observe proof, not that the capability is impossible;
• a tool directory with each visible tool name, schema size, calls, successes, failures, average duration, P95 duration, aggregate input/output byte counts, and configured effect classification;
• click-to-expand per-tool records for the retained bounded sample, with start time, duration, input/output byte counts, result status, effect, and a safe failure category;
• evidence and call-ledger truncation flags so a capped report is distinguishable from a complete one;
• attribution guidance. Unmatched tools appear as Unattributed tools with an explicit explanation that they are loaded but waiting for profile mapping.

The command uses the receiving agent scope automatically, so the report's scope and tool directory match the agent that invoked it. The underlying snapshot JSON contract remains unchanged; the structured report is emitted as a separate log-only session event and is linked to the command result with sourceEventSeq when the session API is available.

The Web renderer presents the report as a product label first and a debugger second. It opens with the runtime identity, compact status pills, one-sentence verdict, and a single summary line for tools, schema, calls, and failures; file and domain activity are quieter secondary facts. The declared-versus-observed capability matrix and attribution notice use flat sections rather than nested metric cards. The primary tool directory is visible in a bounded scroll region with Tool, State, Usage, Avg, P95, Input / Output, and Effect columns. State is limited to Idle, Active, Healthy, Failed, or Discarded, and usage shows calls, successes, failures, or in-flight work from the bounded report. Clicking a tool expands its retained records with start time, duration, input/output byte sizes, result status, effect, and safe failure category. The all-call trace remains a progressive disclosure. The event contract currently exposes byte counts rather than tokenizer-backed token counts, so the UI labels these values as bytes and does not estimate tokens. The visual refinement does not change the Host report, Unicode fallback, snapshot schema, bounded evidence, or raw-payload retention policy.

What the model sees

None. The command and report event are human/debugging surfaces and do not add prompt content.

Token effect

Zero direct tokens. A caller may choose to copy the report into a conversation, but that copy is outside this package.

KV Cache effect

No direct model request and no cache invalidation. Runtime observation continues independently of model prompt assembly.

Known Limitations and Deferred Work

• Tool attribution depends on exact names and prefixes supplied by the deployment; generic runtime events do not prove Cordis plugin ownership.
• Generic DSH events cannot fully prove subprocess creation, credential resolution, persistence, or hidden provider-side network activity.
• Network evidence only covers HTTP(S) URL strings found in bounded tool arguments.
• The package intentionally does not publish a scalar safety or trust grade.
• The current standalone package uses dsh.runtimePeers until the public DSH RC dependency graph is complete.
• The aggregate snapshot is process-local; the optional report event is bounded and log-only, not a long-term audit archive.

Extension points

The collector is a pure state fold and can be consumed without the command plugin. A deployment can add another renderer, export snapshots to a local telemetry sink, or attach policy decisions to the same tools/* and fs/* events without changing the JSON contract.

Development

CI=1 pnpm install --frozen-lockfile
CI=1 pnpm check

pnpm check runs oxlint, TypeScript, coverage, the build, and package hygiene. See CONTRIBUTING.md for the contributor workflow and docs/architecture.md for the implementation model.

License

MIT. See LICENSE.