orgx-deepseek-harness-plugin

OrgX for DeepSeek Harness

@useorgx/deepseek-harness-plugin adds OrgX MCP tools to a DeepSeek Harness profile and can run a workspace-bound OrgX gateway peer through Harness headless mode.

This package is a developer preview. A package install proves only that the bundle is present; it does not prove OrgX authentication, gateway admission, a successful dispatch, deployment, or production use.

Install with the OrgX wizard

The supported user flow is the OrgX wizard. It detects a compatible DeepSeek Harness installation, installs this package into the headless profile, and pairs OrgX in the browser:

npx @useorgx/wizard@latest setup

Then launch a task through the wizard so it can refresh the OAuth token before DSH starts:

npx @useorgx/wizard@latest deepseek "List the OrgX tools available in this workspace."

The DSH bundle fails startup when its MCP connection or initial tool sync fails. Do not treat package presence as proof that the OrgX tool surface is authenticated.

Install the bundle directly

DeepSeek Harness is pinned to 0.1.0-rc.6. Advanced users can install the package directly with Node ^22.19.0 or >=24.0.0:

npm install --global @deepseek-ai/dsh@0.1.0-rc.6
export ORGX_MCP_ACCESS_TOKEN='your_orgx_oauth_access_token'
export DEEPSEEK_API_KEY='your_deepseek_key'
dsh plugin --profile headless add @useorgx/deepseek-harness-plugin@0.1.0
dsh --profile headless --dump-config
dsh --profile headless "List the OrgX tools available in this workspace."

For source development, run npm pack --ignore-scripts and install the resulting tarball with a file: URL. A bare local link does not provide the same clean-install guarantee.

The package vendors the exact MIT-licensed OrgX gateway peer client from @useorgx/orgx-gateway-sdk@0.1.0-alpha.9 commit 49f3cad612954c448878dc62d0f9c6bc87fa0f79. DSH blocks Git and other exotic subdependencies while installing plugins, so bundling that audited client is what keeps a fresh profile installable. See THIRD_PARTY_NOTICES.md.

The bundle mounts one @deepseek-ai/dsh-mcp-client instance named orgx. It connects to https://mcp.useorgx.com/mcp over Streamable HTTP and sends Authorization: Bearer $ORGX_MCP_ACCESS_TOKEN. That value must be a client-managed OrgX OAuth 2.1 access token; the oxk_ gateway key is not valid for hosted MCP. Set ORGX_MCP_URL to use another OrgX MCP endpoint. Startup fails when the OAuth token is missing or the initial MCP connection and tool sync fail. This preview does not run the browser PKCE flow or refresh tokens; replace the client-managed access token when it expires.

DeepSeek Harness 0.1.0-rc.6 bridges MCP tools only. MCP Resources and Prompts are not available through this client. Non-text MCP blocks also have a lossy model-facing projection even when the execution-local result retains their JSON blocks.

Run the OrgX peer

The peer sets the execution cwd inside ORGX_WORKSPACE_ROOT; a requested repository that resolves outside that directory fails before Harness starts. This is a path and mutation boundary, not host isolation. Harness workspace-write does not confine same-user file reads, process visibility, or network access, so a model or tool can observe other host data or send data over the network. Set ORGX_DEEPSEEK_HOST_ACCESS_ACK=1 only after accepting that risk; startup and credential readiness fail without the acknowledgement.

Use an API key scoped for gateway:drive and plugin:heartbeat. The OrgX gateway-key response returns an installation_id; keep that stable value with the key and pass both unchanged on every start.

export ORGX_API_KEY='oxk_your_workspace_key'
export ORGX_MCP_ACCESS_TOKEN='your_orgx_oauth_access_token'
export DEEPSEEK_API_KEY='your_deepseek_key'
export ORGX_WORKSPACE_ID='your-workspace-uuid'
export ORGX_INSTALLATION_ID='install.your-stable-installation-id'
export ORGX_WORKSPACE_ROOT='/absolute/path/to/the/workspace'
export ORGX_DEEPSEEK_HOST_ACCESS_ACK='1'
dsh plugin --profile headless exec orgx-deepseek-harness-peer

This preview is an unmanaged gateway protocol v1 peer. It does not implement the candidate/canonical activation and promotion lifecycle. Supplying ORGX_RUNNER_INSTANCE_ID, ORGX_ACTIVATION_ATTEMPT_ID, or ORGX_RUNNER_ROLE fails startup clearly; those fields are never sent in its heartbeat or socket URL.

Before opening its WebSocket, the peer writes a gateway heartbeat with transport and dispatch readiness false. It advertises dispatch readiness only after all of these checks succeed:

• dsh --version proves the pinned runtime process is alive;
• the pinned official https://api.deepseek.com/user/balance endpoint accepts DEEPSEEK_API_KEY and reports is_available: true without making an inference request; and
• an MCP Streamable HTTP initialize plus tools/list exchange accepts ORGX_MCP_ACCESS_TOKEN.

Secret presence and a credential-free version command are never treated as authentication. Probe failures, rejected or expired credentials, and missing evidence remain fail-closed. Successful evidence is cached for 45 seconds; the peer refreshes gateway presence every 15 seconds and writes a best-effort offline heartbeat when the socket closes.

The DSH child receives the provider key and separately scoped MCP access token, but not the gateway key. Ambient DSH_* controls are not forwarded except DSH_HOME; the child is forced to workspace-write permission and telemetry is disabled so ambient full-access or OTLP-export settings cannot override those two policies. These settings still do not isolate host reads, processes, or network access.

Optional runtime settings:

• ORGX_BASE_URL changes the OrgX gateway base URL.
• ORGX_RECEIPT_OUTBOX_PATH sets an absolute durable-receipt directory. The default is under the current user's OrgX state directory.
• ORGX_DEEPSEEK_HARNESS_BIN changes the executable path from dsh.
• ORGX_DEEPSEEK_HARNESS_PROFILE changes the profile from headless.
• ORGX_DEEPSEEK_HARNESS_MODEL activates the packaged model patch for the deepseek-official provider. It changes the composition default; a model already saved in DSH settings can still take precedence.

Harness headless stdout contains final assistant text and an exit code, but no token or cost accounting. The driver wire message must therefore carry numeric tokens_used: 0 and cost_estimate_cents: 0; both mean unknown at this source, not free. OrgX canonicalizes the persisted DeepSeek cost to its conservative dispatch estimate, records metering quality, and accumulates that estimate in budget caps. A zero process exit reports outcome_kind: awaiting_review: the process finished, but the work is not yet accepted, merged, deployed, or production-proven.

The SDK's WebSocket send has no server acknowledgement, so the application owns durability. Before yielding task.started, the peer atomically writes a pre-start reservation marker. If that write fails, it closes the inner iterator before Harness can spawn and best-effort POSTs a blocked receipt. Before yielding every post-start task.completed frame, it atomically writes the exact v1 HTTP receipt to the mode-0700 outbox using a mode-0600 file, then POSTs it to the idempotent run-receipt endpoint. No key or token is written to either file.

Only a 2xx response removes a terminal receipt. If final persistence fails after Harness has completed, the peer immediately attempts the bound HTTP receipt directly and still yields the original completion. A 2xx clears the reservation; if HTTP also fails, the completion stays in an in-memory retry queue and its reservation marker remains. Pending receipts retry on startup, reconnect, and every 15-second heartbeat tick. A restart with an unresolved reservation fails closed with a repair message instead of risking re-execution.

The pinned SDK cannot durably recover socket-only task.failed. After a run has started, this peer therefore records the failure reason as a step and emits outcome_kind: blocked; cancellation emits outcome_kind: abandoned. Both use the application outbox. A duplicate rejected before task.started remains task.failed and cannot terminalize the dispatch that already owns that run id.

Validate

For package development, install the pinned dependencies without lifecycle scripts, then run the deterministic checks:

npm install --ignore-scripts --no-package-lock
npm run validate

The package test script runs node:test explicitly over test/*.node-test.mjs. The Node-only suffix keeps these suites out of the repository's root Vitest discovery while preserving them in npm run validate.

Validation checks the bundle and manifest, evidence-backed readiness, workspace and child-environment boundaries, cancellation and duplicate races, unmanaged protocol-v1 heartbeats, and the pinned SDK's disconnect-time HTTP failure recovery. It does not contact OrgX or DeepSeek.