dsh-loopx-plugin

LoopX for DeepSeek Harness

dsh-loopx-plugin is one independently versioned DSH package with four cooperating surfaces (three Loader rows and one Client panel):

• the init row automatically installs or upgrades the LoopX CLI, installs the packaged workflow skills into $DSH_AGENTS_HOME/skills (default ~/.agents/skills), and verifies the DSH-native loopx entry before DSH finishes loading it. /loopx-init remains the explicit repair command.
• a passive same-session Driver becomes eligible only after the exact current Session successfully invokes the exact loopx skill. It then asks LoopX whether another turn may run and queues the authoritative heartbeat task into that live DSH Agent.
• the package-root Host registers GoalBar at the authenticated /api/loopx.goalbar route required by DSH 0.1.5. Its web Client adds a compact GoalBar between DSH's native GoalBar and Queue dock rows, visible only for one exact live (goalId, loopxAgentId) binding.
• the web Client also adds one global sidebar entry, LoopX, whose central panel embeds the already-running personal workspace from loopx dashboard on loopback. The panel is presentation only: it starts no service, reads no LoopX state itself, and renders a recovery notice plus retry when that loopback service is absent.

Installing the plugin and starting DSH load and prepare these capabilities; neither creates a binding nor activates the Driver. The GoalBar does one bounded read when a browser row mounts, then watches exact-Session step/end and turn/end boundaries. It rereads LoopX only when the opaque revision of the authoritative binding or active Goal state changes; a watch lease also detects changes written outside that Session. DSH Agent-status events update an existing row without a LoopX business read. Until one exact Session contains valid typed loopx invocation evidence, its Driver makes no LoopX CLI, binding, quota, or heartbeat call, creates no timer, and queues no followup.

The package does not expose LoopX model tools, a binding sidecar, or its own Goal/Todo state. Models use the installed LoopX skills and call the LoopX CLI directly. LoopX remains the only authority for Goal, Agent, Todo, quota, activation, and durable thread-binding data. The GoalBar protocol and its deferred atomicity limit are specified in the versioned DSH native LoopX design.

Install

Requirements are stable Node.js 22.22.3+ (excluding Node.js 23), pnpm, Python 3.11+ with pip, and network access for the first DSH start when no compatible LoopX CLI is already installed. LoopX itself is deliberately not a prerequisite. The initializer honors an explicit PYTHON_BIN; otherwise it tries python3, then discovers python3. executables on the supplied PATH in descending numeric order, then tries the bare name python. The last name is what a python.org Windows install registers, so it keeps that host reachable when python3 is absent or is the WindowsApps App Execution Alias that never starts Python. Unlike the versioned names it is not a PATH scan result; it is resolved when the candidate runs. Installation still checks the Python version and pip; reopening the managed runtime uses the same discovery and validates the LoopX CLI. No hard-coded minor-version list is maintained. When selecting Python for installation, an invalid explicit interpreter fails instead of falling back. Managed-runtime readback keeps the existing CLI fallback behavior. If the plugin must install or upgrade LoopX, it writes an isolated copy under $DSH_AGENTS_HOME/runtime/dsh-loopx-plugin (default ~/.agents/runtime/dsh-loopx-plugin) and never mutates the system Python environment. This works with externally managed Python distributions that enforce PEP 668; the plugin does not use --break-system-packages. This version requires LoopX 1.2.4 or newer, the published release that includes the Windows peer-file fix. Bootstrap, Driver and GoalBar use the same version floor; an older global or managed CLI is upgraded or rejected before business commands run. An explicit outdated LOOPX_BIN must be upgraded by its owner. Older plugin releases retain their original CLI requirements. The continuation driver follows LoopX's context delivery setting on CLI 2.3 and later. When the guard returns a capture reference, the driver reads the admission fields from that same capture. The driver requests raw admission JSON from older supported CLIs. Install the prebuilt release into the web profile:

dsh plugin --profile web add \
  "https://github.com/loopx-project/loopx/releases/download/dsh-loopx-plugin-v0.1.1-beta.6/dsh-loopx-plugin-0.1.1-beta.6.tgz"

The beta.6 package targets the qualified DSH 0.2.0-rc.2 API and retains the qualified frozen 0.1.5 and 0.1.7-rc.2 compatibility ranges. The exported legacy RPC registration remains available to explicit callers, but plugin startup always uses the shared API.

The source candidate additionally qualifies DSH 0.2.1-rc.2. Its frozen source host uses MCP client 2.3.0 and SDK 1.32.0 to address GHSA-6prh-2h8m-c8cw. These dependency overrides do not patch an independently installed DSH binary; that host's owner must update its affected MCP dependencies separately.

For a compatible DSH source build, use:

cd packages/dsh-loopx-plugin
./install.sh

Start DSH on loopback (port 0 asks the OS for a free port) and open the printed URL. The plugin finishes its idempotent LoopX CLI and skill bootstrap before DSH publishes the Web URL through its native Loader readiness boundary. The source candidate gates only LoopX's Host and Driver on loopxBootstrap, so disabling or uninstalling it keeps the shared Web server and runtime alive. The published beta.6 limitation is described under automatic initialization:

dsh --profile web --port 0

Use /loopx immediately. If automatic initialization reports a safe failure in the DSH log, fix the named Python or package-manager problem and run /loopx-init once to retry; normal installation does not require that command.

Installation is the GoalBar opt-in: there is no separate remote endpoint or per-session grant. A row remains hidden until the exact DSH Session has one unique LoopX binding. After invoking the installed loopx skill for that Session, run the minimum authority readback inside that Session's DSH shell (or replace $DSH_SESSION_ID with the exact Session id):

loopx --registry .loopx/registry.json --format json \
  resolve-agent-thread \
  --host-surface deepseek-harness-native \
  --thread-id "$DSH_SESSION_ID"

status=bound with one exact pair admits the row; missing or ambiguous results fail closed and render nothing. Start resumes a stopped Goal and asks the Driver to evaluate only when that exact live Session already contains typed loopx skill activation evidence. It never activates an inactive Session. Pause stops the Goal and retires only future queued/scheduled continuation; it does not abort a claimed or running turn.

To start DSH from a terminal with this machine's stored LoopX provider credential without placing the value in argv, shell history, or output:

loopx dsh-launch web

The launcher uses DSH_HOME when set, otherwise ~/.local/state/loopx/dsh-home. Ordinary DSH installation defaults to ~/.dsh; launching the isolated home does not reuse that home's installed plugins. To reuse an ordinary installation, select its actual home explicitly:

loopx dsh-launch --dsh-home "${DSH_HOME:-$HOME/.dsh}" web

For a new isolated source installation, use the same home and package-local host for installation, readback, launch, and removal:

cd packages/dsh-loopx-plugin
export DSH_HOME="$HOME/.local/state/loopx/dsh-home"
./install.sh
export DSH_BIN="$PWD/node_modules/.bin/dsh"
"$DSH_BIN" --profile web --dump-config
loopx dsh-launch --dsh-bin "$DSH_BIN" web
# When removing this installation:
"$DSH_BIN" plugin --profile web remove dsh-loopx-plugin

Use --dsh-home to select profile and Session state, --dsh-agents-home to isolate installed skills, and --dsh-bin when dsh is not on PATH. Arguments after -- are passed to DSH unchanged. The launcher resolves the same write-only machine credential used by the managed executor, then replaces itself with DSH so the credential exists only in the child process environment.

Maintainers can validate the built and packed surfaces with:

pnpm build
pnpm smoke:mcp-transport
pnpm smoke:artifact
pnpm smoke:profile
pnpm smoke:runtime
pnpm smoke:docker

The runtime smoke creates an isolated temporary DSH profile. Its real web process proves profile composition, automatic initialization before readiness, immediate skill-catalog visibility, boot-manifest discovery, bundle serving, Client materialization, and the loopback Connection fence. A live-disable probe withdraws the bootstrap provider and all package rows while checking that DSH stays available and LoopX's route retires; a fresh process also boots with the whole package disabled. Separately, a packed supported-DSH Context, Connection, and WebServer with a live Host Session fixture cover same-turn binding discovery, lease-time source reconciliation, status-only updates, pending-watch cancellation, successful actions, and handler disposal through the real HTTP carrier. The served Client is then applied in DSH's real ClientModuleSystem with a VM document harness; that layer covers slot order and coexistence, Session injection, and ordinary-unload/HMR style cleanup, but it is not a browser-mounted React interaction. These layers do not replace the owner-reviewed packed-browser gate: that separate manual layer mounts the served Client at a real DSH URL and exercises Client-to-carrier Start/Pause. Focused Client tests cover Session-generation replacement and old request cancellation without duplicating that matrix in the packed smoke. The Docker smoke packs the current plugin and builds the current LoopX release-candidate wheel, then starts both in a clean Debian container with the DSH 0.1.5-rc.2 release candidate. It proves PEP 668-compatible private installation, the managed launcher, startup readiness, installed loopx skill files, launch- token authentication, and an authenticated GoalBar read through DSH's shared API carrier. It requires Docker, uv, and network access for base images and never opens a browser or configures a model provider.

Maintainer release and marketplace handoff

A DSH plugin release needs an immutable prebuilt GitHub asset and a qualified install channel in each marketplace named in its closeout. The awesome-dsh-plugin directory and DSH Plugin Hub have distinct published catalogs. Current Hub releases read https://api.dsh-plugin.org/plugins.en.json and plugins.zh.json; updating the awesome directory does not update those consumers. Marketplace maintainers retain authority over their own catalogs.

Pinned GitHub release installation does not require publishing LoopX on npm. Release-URL installed-state matching shipped in Hub 1.5.0. Qualification must read the actual marketplace's catalog back, select the pinned package, install it, recognize the installed row, update it and remove it successfully. The optional npm channel retains its separate account and trusted-publisher requirements.

For every DSH plugin release:

1. Update the package version and this README's pinned install URL. Run the typecheck, tests, and the built, packed, runtime, profile, and Docker smokes listed above, plus pnpm smoke:registry --tarball . The registry smoke serves the real packed bytes on loopback and invokes DSH's unversioned package-name installer; it publishes nothing. CI repeats this installation and removal on Linux and Windows. Qualification uses pnpm 10.33.0; use that version for reproducible source and isolated-registry checks.

2. Prepare complete bilingual GitHub release notes. Run examples/release/release-readiness-doc-smoke.py with one --surface for every optional capability changed by the release.

3. Merge the exact reviewed commit, pack from that immutable tag target, and publish both the version tag and dsh-loopx-plugin-.tgz asset.

4. Read the remote release body back and rerun the release-readiness smoke. Download the remote asset and verify that its SHA-256 matches the local package before advertising it. For the npm channel, publish that same tarball, including its compiled Host, Client, Driver and initializer:

   npm whoami
   npm publish ./dsh-loopx-plugin-VERSION.tgz --access public --tag latest
   node scripts/verify-distribution.mjs --tarball ./dsh-loopx-plugin-VERSION.tgz
   

   latest intentionally names the qualified plugin candidate, because the marketplace installs its unversioned npm name. Do not substitute a beta-only tag or publish the monorepo root. The readback checks metadata, tag, downloaded bytes and the repository search used by DSH Hub. A missing package, wrong artifact or search-index delay fails verification; publishing alone does not complete marketplace recovery. npm account authentication or configured trusted publishing belongs to the release operator.

   For token-free CI publication, configure the package's npm Trusted Publisher with organization loopx-project, repository loopx, and workflow filename dsh-plugin-publish.yml, permitting npm publish. Then dispatch Publish DSH Plugin to npm on the existing published plugin tag, using that same tag for the release_tag input. This keeps npm provenance on the artifact's commit. The workflow requires a merged tag, consumes its GitHub asset without rebuilding, and verifies npm bytes and discovery. It neither creates a GitHub release nor replaces npm account ownership or the release guide gate.

5. For the awesome directory, in a clean fork branch of awesome-dsh-plugin, update only data/plugins/loopx-project__loopx--packages-dsh-loopx-plugin.yml to the new immutable asset URL. Confirm the URL resolves, then run node scripts/generate-readme.mjs --check and git diff --check.

6. Open the upstream directory pull request and link it from the release closeout. Separately verify the installed Hub's catalog source at the released Hub revision. Read both language feeds and the website's install command; for the LoopX row, check the ic and igc targets against the immutable release URL. Route stale Hub metadata to its existing data-correction issue channel. Keep that marketplace's adoption open until its actual consumer resolves and installs the released package. A merged directory PR, another catalog's listing, or an upgraded Hub cannot establish that postcondition.

Shadow observer (default off)

src/observer.ts, exported as dsh-loopx-plugin/observer, is the dsh-session-events provider for the LoopX Reliability Diagnostics capability: an L1 shadow observer that consumes read-only harness events and appends compact, public-safe envelopes plus an observer stats record to /reliability_diagnostics/by-goal/.ndjson, where sha256 is the lowercase digest of the exact UTF-8 Goal id. Upgrade the CLI and plugin together. An existing legacy filename blocks flushes with LegacyDiagnosticLedgerError until the [offline upgrade](../../loopx/capabilities/reliability_diagnostics/docs/local-retention-v0.md#upgrading-a-leg