forgeax-dsh-game-plugin

@forgeax/dsh-game

ForgeaX game development inside DeepSeek Harness. This is a DSH bundle: installing it into a profile adds one patch layer that wires the already-published @forgeax/game MCP server, its bundled ForgeaX Skills, and a workspace guard into your DSH session.

It contains no game logic and no copy of ForgeaX. It resolves the @forgeax/game package that pnpm installed next to it, verifies its identity, and connects it.

What you get

Surface	Effect
Tools	mcp__forgeax__forgeax_status_lite, mcp__forgeax__forgeax_run_current_game
Skills	forgeax-game plus every forgeax-engine-* Skill shipped in the resolved package, registered on ctx.skills at boot
Guard	Every mcp__forgeax__* call whose target_dir is not the current session cwd is denied. A call that carries no session cwd to compare against (Code Mode, nested dispatch) is allowed after an existence check, and the model is told it was not fully checked

You do not run forgeax-game devkit install. This bundle registers the Skills directly; running the installer as well only leaves duplicate copies in your repo that DSH never reads.

Requirements

• macOS arm64, Linux x64, or Windows x64. This bundle is pure JS and declares no os/cpu; it inherits its platform reach from @forgeax/game, whose @forgeax/game-runtime ships a native binary as one optionalDependencies entry per platform. Your machine installs only the matching one. Platforms with no published variant (Intel Mac, ARM Linux, ARM Windows) install cleanly but fail when the runtime starts, exactly as @forgeax/game does on its own.
• pnpm on PATH. dsh plugin is a thin pnpm forwarder; without pnpm it exits 127.
• Node ≥ 22, matching DSH.

Install

dsh plugin installs into one named profile and self-activates: because this package declares dsh.bundle, adding it as a dependency also appends it to that profile's dsh.profile.bundles layer stack.

dsh plugin --profile web add @forgeax/dsh-game

--profile is mandatory — DSH has no implicit default profile, and the layer stack is per profile. Repeat the command for every profile that should have ForgeaX.

Then restart dsh. Bundle layers are read once at boot; only the profile's own user patch file is watched. A freshly added bundle is inert until the next launch.

Verify after restarting:

dsh --profile web
# then, in the session:
#   ask for the ForgeaX status — the model should call mcp__forgeax__forgeax_status_lite

Configuration

The four rows this bundle inserts, all namespaced so they can never collide with another bundle:

Row id	Module	Purpose
forgeax-game.launch-spec	@forgeax/dsh-game/launch-spec	Resolves + verifies @forgeax/game, publishes the forgeaxGameLaunch service
forgeax-game.mcp-client	@deepseek-ai/dsh-mcp-client	stdio bridge, serverName: forgeax
forgeax-game.skill-source	@forgeax/dsh-game/skill-source	Registers the package's Skills
forgeax-game.workspace-guard	@forgeax/dsh-game/workspace-guard	Tool policy: denies on tools/pre-execute, reports an unverifiable call on tools/post-execute

The resolver itself lives in a fifth module, @forgeax/dsh-game/forgeax-package, which imports no framework. Provenance tooling can load it from an installed profile, where the DSH packages are peers the profile never installs a second copy of.

To change something, add a row with the same id to your profile's user patch file. A patch replaces the whole config of the targeted row — there is no deep merge — so you must restate every field you want to keep. For example, to shorten the tool-call timeout:

# $DSH_HOME/profiles/web/cordis.patch.yml
- insert:
    - id: forgeax-game.mcp-client
      name: '@deepseek-ai/dsh-mcp-client'
      inject:
        - forgeaxGameLaunch
      config:
        serverName: forgeax
        transport: stdio
        command: !!js ctx.forgeaxGameLaunch.spec.command
        args: !!js ctx.forgeaxGameLaunch.spec.args
        cwd: !!js ctx.forgeaxGameLaunch.spec.cwd
        env: !!js ctx.forgeaxGameLaunch.spec.env
        failOnStartupError: true
        toolCallTimeoutMs: 120000
        reconnect:
          enabled: true

Limits worth knowing

• Tools only. DSH's MCP client bridges tools, not resources. forgeax://status is unreachable in a DSH session; mcp__forgeax__forgeax_status_lite returns the same state. The registered Skill says so, so the model does not try the resource.
• No transitive bundles. Only packages listed directly in dsh.profile.bundles contribute a patch layer. A bundle that depends on this one does not inherit its rows.
• One-time ForgeaX operations stay on the CLI. Creating a game, switching the active game, and upgrading the plugin are forgeax-game <init|use|doctor|devkit|upgrade> subcommands, not MCP tools.

Failure modes

Symptom	Cause
dsh plugin exits 127	pnpm not on PATH
Runtime fails to start after a clean install	no @forgeax/game-runtime variant for this platform (Intel Mac, ARM Linux, ARM Windows) — none is published yet
pnpm refuses a git-hosted spec's prepare	allowlist it under allowBuilds in <profileDir>/pnpm-workspace.yaml (pnpm ≥ 10)
ForgeaX tools absent after install	dsh not restarted
Boot fails with a launch-spec error	the resolved @forgeax/game does not match the pinned version or is missing bundled Skill assets — reinstall rather than patching around it

failOnStartupError is true on purpose: a ForgeaX session whose MCP server never started is broken, not degraded, and a boot-time error is cheaper to read than a mystery at the first tool call.

Security

• The child process is launched with env: {}. DSH scrubs the parent environment and merges config.env after the scrub, so anything listed there would re-inject a secret the harness just removed.
• The workspace guard compares target_dir against the session cwd after realpath resolution — never by string prefix, which symlinks and .. defeat.
• No API key, token, or secret value is read, stored, or logged by this bundle.

Changelog

Every user-visible change is recorded in CHANGELOG.md. To contribute, see CONTRIBUTING.md; to report a vulnerability, see SECURITY.md.

License

MIT