A local-first multi-agent app development platform, built on PenguinHarness
/**
* @adelie/sandbox-dsh — the DeepSeek Harness sandbox ecosystem
* behind this harness's own sandbox interface.
*
* A PLUGIN PACKAGE, not part of the platform: a Project asks for it on the Plugins page
* and the harness resolves it from the installation (see the server's plugin/loader.ts).
* The DSH dependencies live HERE, in this package — the harness itself does not depend
* on them, which is what "plugins are configuration, not built-in capability" means in
* dependency terms.
*
* `@deepseek-ai/dsh-sandbox-local` carries the platform chain (dsh-bwrap → Landlock on
* Linux, Seatbelt on macOS, the ACL restricted-token runner on Windows) and probes them
* functionally; this file translates between its vocabulary and ours. Because DSH's
* policy vocabulary governs file-write effects only, the adaptor declares exactly
* `fs-write` — the service therefore never routes a network / mask-paths policy here,
* and the adaptor never has to drop a dimension it cannot honor.
*
* Everything DSH loads behind the dynamic imports below, and that is load-bearing for
* hot push (see scripts/deploy.mjs): the package reaches native-adjacent modules that a
* pushed single-file bundle resolves from the installation, so an installation missing
* them fails THIS load — reported fail-closed by the service — instead of failing the
* whole platform bundle's import.
*/
import { tmpdir } from "node:os";
import path from "node:path";
import { Bind, Component } from "@adelie/core/plugin";
import type {
ConfinedArgv,
Plugin,
SandboxLimit,
SandboxProvider,
SandboxProviderSource,
} from "@adelie/core/plugin";
/**
* Programs the Windows ACL restricted-token runner cannot start — and they include the harness's
* Windows default session shell (Git for Windows' bash, or the `sh.exe` of the MinGit the
* Windows package bundles). Measured on windows-latest: a bare `bash`
* reaches System32's WSL launcher before PATH ("Error code:
* Bash/Service/CreateInstance/E_ACCESSDENIED"), and an MSYS bash or sh named by path aborts
* under the write-restricted token ("fatal error - couldn't create signal pipe, Win32 error
* 5" / "CreateFileMapping …, Win32 error 5"). In the same run both PowerShells ran confined,
* writing inside the Workspace and denied outside it: pwsh 7.6.6 and Windows PowerShell 5.1.
*
* The abort is the MSYS runtime's (msys-2.0.dll, shared by Git for Windows and MSYS2), not
* bash's, so it is refused by runtime: the POSIX shells those distributions ship, by name, and
* any program in an MSYS `usr\bin` — the directory where every binary links that runtime.
*/
const MSYS_SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh", "mksh", "fish", "git-bash"]);
/** What the backend reads of the harness's session shell (core's `ShellInvocation`). */
export interface SessionShell {
/** Executable name or path the harness spawns commands with. */
command: string;
}
const unstartable = (program: string): boolean => {
const segments = program.toLowerCase().split(/[\\/]+/);
const base = (segments.at(-1) ?? "").replace(/\.exe$/i, "");
return MSYS_SHELLS.has(base) || (segments.at(-3) === "usr" && segments.at(-2) === "bin");
};
/** The one setting that fixes an MSYS-runtime session shell, as every refusal of it words it. */
const SESSION_SHELL_FIX =
"Set ADELIE_SHELL=pwsh (PowerShell 7) — or ADELIE_SHELL=powershell (Windows PowerShell " +
"5.1) where PowerShell 7 is not installed — in the harness's environment and restart it";
/**
* Fail this backend's load on Windows when the harness's session shell is one its ACL runner
* cannot start. A backend whose load fails is not mounted: the sandbox service reports it with
* this reason (the Session view's `unavailableBackends`), so the confining tier shows as
* unavailable with the fix, rather than selectable and then refusing every command. `null` is
* a host core that does not export the session shell (an older runtime): nothing is checked,
* and `assertAclRunnerCanStart` still refuses per command.
*/
export function assertSessionShellConfinable(
shell: SessionShell | null,
platform: NodeJS.Platform = process.platform,
): void {
if (platform !== "win32" || shell === null || !unstartable(shell.command)) return;
throw new Error(
`sandbox-dsh cannot confine commands on Windows under the session shell "${shell.command}": ` +
"its ACL runner does not start bash, sh or any other MSYS-runtime program (Git for " +
"Windows, the bundled MinGit, MSYS2). " +
`${SESSION_SHELL_FIX}.`,
);
}
/**
* Refuse, before the runner is involved, a spawn whose program the ACL runner cannot start.
* Without this every confined command still fails closed, but with the runner's error — which
* names WSL or an MSYS internal, not the setting that fixes it. The same `confine()` carries a
* stdio MCP Server's launch command, which `ADELIE_SHELL` does not choose: only a program that
* IS the session shell is pointed at that setting. A `sessionShell` of `null` (a host core that
* does not export it) cannot tell the two apart and keeps the session shell's wording.
*/
export function assertAclRunnerCanStart(
argv: readonly string[],
platform: NodeJS.Platform = process.platform,
sessionShell: SessionShell | null = null,
): void {
const program = argv[0];
if (platform !== "win32" || program === undefined || !unstartable(program)) return;
if (sessionShell === null || sessionShell.command.toLowerCase() === program.toLowerCase()) {
throw new Error(
`sandbox-dsh cannot confine "${program}" on Windows: its ACL runner does not start bash, ` +
`sh or any other MSYS-runtime program (Git for Windows, the bundled MinGit, MSYS2). ` +
`${SESSION_SHELL_FIX}; refusing to run the ` +
"command unconfined.",
);
}
throw new Error(
`sandbox-dsh cannot confine "${program}" on Windows: its ACL runner does not start bash, ` +
"sh or any other MSYS-runtime program (Git for Windows, the bundled MinGit, MSYS2, or " +
"System32's WSL launcher); start the program " +
"directly, or through PowerShell; refusing to run it unconfined.",
);
}
/**
* The host's plugin contract, named by a variable so this package's bundle leaves the import to
* run time: tsup inlines `@adelie/core/plugin` for the decorators (a literal
* specifier), and a second, bundled copy of the session shell would be this package's
* resolution, not the harness's. Resolved where the plugin runs, from the installation; where
* the host's core cannot be reached the import fails and `hostSessionShell` returns `null`.
*/
const HOST_CORE: string = "@adelie/core/plugin";
/**
* The harness's session shell, from the host's core; `null` when that core does not export
* `sessionShell` (it arrived after the runtimes a hot push may still be running on) or cannot
* be reached. Read by namespace, never as a static named import: a missing export must not
* fail this module's linking. `load` is injectable for tests.
*/
export async function hostSessionShell(
load: () => Promise<unknown> = () => import(HOST_CORE),
): Promise<SessionShell | null> {
let core: { sessionShell?: unknown };
try {
core = (await load()) as { sessionShell?: unknown };
} catch {
return null;
}
return typeof core.sessionShell === "function" ? (core.sessionShell() as SessionShell) : null;
}
/** What `loadDshAdaptor` reads of the running process; injectable for tests. */
export interface DshLoadHost {
platform?: NodeJS.Platform;
/** The session shell, `null` for a host core without one; read from the host when absent. */
sessionShell?: SessionShell | null;
}
/**
* The rung DSH's chain selected, by the program its wrap starts: on Linux bubblewrap when it
* passed the chain's probe, else the Landlock launcher; one rung each on macOS and Windows.
*/
export function rungName(platform: NodeJS.Platform, runner: string | undefined): string {
if (platform === "darwin") return "Seatbelt";
if (platform === "win32") return "the Windows ACL runner";
return runner === "bwrap" ? "bubblewrap" : "Landlock";
}
/**
* What the rung leaves open, for the settings card. DSH's policy takes the mode and the
* Workspace and nothing more, so no rung grants the Session's scratchpad (SandboxPolicy
* .writableRoots). Landlock grants the host's own /tmp; on a kernel older than Landlock ABI 5
* the launcher governs only part of the file accesses, and says so on every run (dropped from
* the command's stderr, see the core's ConfinedSpawn.runnerLines).
*/
export function rungLimits(rung: string, enforcement: "full" | "partial"): SandboxLimit[] {
const limits: SandboxLimit[] = [
{
text: `${rung}: under Workspace Write the Session scratchpad is not writable — DSH's policy takes the Workspace alone — so commands cannot write the plan, goal or attachment files kept there.`,
textZh: `${rung}:仅工作区可写下 Session scratchpad 不可写(DSH 的策略只接受工作区),命令无法写入其中的计划、目标与附件文件。`,
},
];
if (rung !== "Landlock") return limits;
limits.push({
text: "Landlock: under Workspace Write the temporary directory is the host's shared /tmp, writable by every confined command; it cannot be closed or made private here.",
textZh:
"Landlock:仅工作区可写下,临时目录就是宿主共享的 /tmp,每条受限命令都可写;本机无法关闭它,也无法让它私有。",
});
if (enforcement === "partial") {
limits.push({
text: "Landlock (partial): this kernel's Landlock ABI is older than 5 (Linux 6.10), so ioctl on device files outside the Workspace is not restricted; below ABI 3 (Linux 6.2) truncating a file outside the Workspace is not restricted either.",
textZh:
"Landlock(partial):本机内核的 Landlock ABI 低于 5(Linux 6.10),工作区外设备文件上的 ioctl 不受限制;低于 ABI 3(Linux 6.2)时,截断工作区外的文件也不受限制。",
});
}
return limits;
}
/**
* Mount the stock DSH chain on a bare cordis Context — exactly how DSH's own tests mount it —
* after checking, on Windows, that its ACL runner can start the session shell at all.
*/
export async function loadDshAdaptor(host: DshLoadHost = {}): Promise<SandboxProvider | null> {
const platform = host.platform ?? process.platform;
const shell =
platform !== "win32"
? null
: host.sessionShell !== undefined
? host.sessionShell
: await hostSessionShell();
assertSessionShellConfinable(shell, platform);
const { Context } = await import("@deepseek-ai/cordis");
const { LocalSandboxProvider } = await import("@deepseek-ai/dsh-sandbox-local");
const ctx = new Context();
// `ctx.plugin` is cordis's own API name, not this repo's vocabulary.
await ctx.plugin(LocalSandboxProvider, {});
const dsh = ctx.sandbox;
// The chain picks its rung on the first confine; do that here, so the settings card can name
// the rung that serves. On Linux, whose chain has two rungs, that is the chain's functional
// probes (DSH keeps the verdict for the provider's lifetime), and a host where neither works
// fails this load with DSH's reason instead of mounting a backend that refuses every command.
// macOS and Windows have a single rung, which DSH selects unprobed: this proves nothing there.
const probe = dsh.confine([process.execPath], { mode: "read-only", workspaceRoot: tmpdir() });
const rung = rungName(platform, probe.argv[0]);
return {
// DSH's own words: "Network and process visibility are outside this vocabulary." Nor can it
// close the temporary directory (`closed-temp`): every rung grants one under workspace-write.
dimensions: ["fs-write"],
mechanism: rung + (probe.enforcement === "partial" ? " (partial)" : ""),
limits: rungLimits(rung, probe.enforcement),
confine(argv, policy): ConfinedArgv {
if (policy.mode === "danger-full-access") {
// Unreachable: this backend implements only fs-write, so the service never hands it a
// full-access policy (which only ever arrives with a network/mask dimension it lacks).
throw new Error("dsh-local does not implement full filesystem access with confinement");
}
assertAclRunnerCanStart(argv, platform, shell);
const confined = dsh.confine(argv, {
mode: policy.mode,
workspaceRoot: policy.workspaceRoot,
});
return {
argv: confined.argv,
enforcement: confined.enforcement,
denialSignatures: confined.denialSignatures,
runnerFailureRules: confined.runnerFailureRules,
};
},
};
}
/**
* The plugin's one module: a provider on the sandbox slot, the code half of the
* contribution the decorator declares (its manifest is generated into ifaces.json from
* here). Created per App, so a hot swap gets a fresh provider.
*/
@Component({
contributes: {
"SandboxModule.providers": [
{ id: "sandbox-dsh.provider", name: "dsh-local", dimensions: ["fs-write"] },
],
},
})
export class SandboxDsh {
@Bind("sandbox-dsh.provider") provider!: SandboxProviderSource;
setup() {
this.provider = loadDshAdaptor();
}
}
const plugin: Plugin = { modules: [SandboxDsh] };
export default plugin;