deepseek-harness/packages/bash/bash-env/README.md

@deepseek-ai/dsh-bash-env

English | 中文

The tool-independent shell environment plugin: owns the ctx.bashEnv registry of trusted, per-execution DSH_* variables that the model-facing shell tools (dsh-tool-bash, dsh-tool-pwsh) collect into every shell call's environment. Built-in shell facts (DSH_HOME, DSH_SHELL=1, DSH_SESSION_ID) are owned by the registry itself; other plugins register additional enumerable facts with effect-scoped disposal, and duplicate ownership or undeclared runtime keys fail loudly.

The package root exports the Cordis plugin contract (name, inject, Config, apply) plus the BashEnvRegistry service class and its contributor types; consumers use ctx.bashEnv after loading this plugin.

Config

- id: bash-env
  name: '@deepseek-ai/dsh-bash-env'
  config:
    dshHome: C:\Users\me\.dsh   # default: $DSH_HOME, then ~/.dsh

Managed environment

Every foreground and background model shell call receives a newly collected trusted DSH_* environment. DSH_HOME is the absolute Harness home resolved by @deepseek-ai/dsh-paths (dshHome config, then ambient $DSH_HOME, then ~/.dsh) and DSH_SHELL=1 identifies the managed child. Agent calls additionally receive DSH_SESSION_ID=agent.session.header.id; when the active persistence seam locates a JSONL artifact they also receive DSH_SESSION_JSONL=<absolute target path>. The JSONL path is a location hint: it may not exist before the first flush or contain the current buffered turn, and it is not an authorization credential.

ctx.bashEnv owns collection. Other plugins can register an effect-scoped contributor with a stable name, declared keys/descriptions, and resolve(execution: ToolExecution); duplicate ownership and undeclared runtime keys fail loudly, while list() enumerates declarations without executing providers. Harness built-ins reserve DSH_HOME, DSH_SHELL, and DSH_SESSION_ID; this plugin's persistence translator owns DSH_SESSION_JSONL by reading the backend-neutral sessionPersistence.locate() seam.

import type { Context } from '@deepseek-ai/cordis'
import type {} from '@deepseek-ai/dsh-bash-env'

export const inject = ['bashEnv']

export function apply(ctx: Context): void {
  ctx.bashEnv.register({
    name: 'deployment-region',
    variables: { DSH_DEPLOYMENT_REGION: { description: 'Current deployment region.' } },
    resolve: execution => execution.agent === undefined ? {} : { DSH_DEPLOYMENT_REGION: 'cn-north' },
  })
}

The overlay is computed from the current ToolExecution and passed through the dedicated BashExecRequest.dshEnv channel. The local executors remove all inherited DSH_* before merging that snapshot, so nested harnesses and concurrent parent/child agents cannot leak stale identities. process.env is never modified. The shell tools' descriptions teach the generic $DSH_* convention rather than naming persistence-specific variables or adding a permanent system-prompt section.

Model Experience

Indirectly, through the shell tools (dsh-tool-bash, dsh-tool-pwsh), which collect this registry's managed DSH_* snapshot into every shell-tool call.

KV Cache effect

No direct invalidation; the named consumers own any request-prefix changes.

Known Limitations and Deferred Work

• list() enumerates contributor-declared variables only — registry-owned built-ins (DSH_HOME, DSH_SHELL, DSH_SESSION_ID) are not included, so diagnostics, prompt, or UI code must not treat list() as an exhaustive environment catalog.