dsh-session-scope
An independent per-session workspace visibility layer for DeepSeek Harness.
A session keeps its original workspace and cwd while exposing only explicitly
selected workspace directories to the agent.
The central policy rule is:
Permission != Scope
Permission controls effects (read-only, workspace-write, or
danger-full-access). Session scope independently controls which part of the
workspace is visible (full, focused, or Linux isolated).
Development status
0.5.0 implements the specification through Phase 4. It currently contains:
- a TypeScript port of the reusable upstream directory picker, path safety,
filesystem fence, and sandbox integration;
- a strict TypeScript session-scope domain model;
- the durable
session-scope/set snapshot and last-write-wins fold;
full, focused, and isolated state vocabulary;- canonical root validation, nested-root collapse, navigation ancestors, and
stable error codes;
- typed host operations (
getScope, setScope, listScopeDirectory, and
getScopeCapabilities) plus the /scope command and session-scope
projection;
- pure visibility rules for content vs. navigation paths, filtered directory
listings, and scoped glob/grep/search roots;
- runtime filesystem enforcement carried per session with
AsyncLocalStorage,
including text and bounded byte reads, plus a monotonic final guard for
known path-aware tools;
- broad
glob/grep composition across selected content roots, including
fail-closed handling for an omitted path and output path revalidation;
- model-facing scope context that exposes accessible roots without naming
hidden siblings;
- an independent
Scope composer chip and tree picker, separated from the
ordinary permission selector;
- Linux
isolated process confinement through DSH's existing bubblewrap
provider for one-shot bash and persistent PTY creation;
- an empty workspace overlay with only selected roots rebound, permission-aware
read-only/writable mounts, and a post-mount working directory;
- functional backend capability detection plus fail-closed handling for
unknown runner profiles, partial enforcement, unsupported platforms, and
danger-full-access;
- a process lifecycle fence that prevents scope changes while foreground or
background shell jobs and persistent terminals retain an old mount view;
- scoped pre-step filesystem context for workspace instructions and project
skill discovery, while user/OS paths outside the workspace retain ordinary
DSH policy;
- fail-closed LSP calls under selected scope because the current upstream LSP
provider indexes the whole session workspace;
- fork inheritance through the durable seed plus fail-closed subagent
initialization before child publication, including nested and resumed
children;
- compatibility folding for legacy
workspace-scope/selection sessions;
- Vitest coverage for the ported primitives and new scope state.
Focused scope covers DSH filesystem services and known path-aware tools, but
does not confine arbitrary shell processes. Isolated scope additionally
confines DSH's supported bash and PTY launch paths when the Linux provider
selects a fully enforcing, recognized bubblewrap profile. It is unavailable on
other backends and cannot currently be combined with danger-full-access;
these combinations fail closed instead of silently degrading to Focused.
Installation
npm install dsh-session-scope
The package ships the DSH bundle patch as cordis.patch.yml and exposes its
server and web-client entry points through the package exports map. Node.js
20 or newer is required.
Development
npm install
npm run check
CI runs the TypeScript build, Vitest suite, package-contract checks, and a
packed-plugin composition smoke test against the DSH releases listed in
compatibility.json on Linux, macOS, and Windows.
TypeScript sources live in src/; npm run build emits distributable ES
modules, source maps, and declarations into lib/. Tests run with Vitest.
Prior art and attribution
The initial directory picker, path canonicalization, filesystem fencing, and
sandbox integration were adapted from
dsh-workspace-scope-selection
by jiangr100, used under the MIT License. The
original copyright notice is preserved in LICENSE.
