AgentKit Studio
Runtimes and deployment

Star Harness

Star Harness as an npm plugin — its execution model, the install/upgrade/bind lifecycle, and why it must be installed before it can be selected.

Star Harness (harness) hands the entire turn to the Harness native kernel, so DSH stops running the model-and-tool loop itself. It has exactly one published form: @kingsoftcloud/agentkit-harness-node installed from npm. There is no separate process and no engine address for you to write — once you have installed it on the plugin page, enabled it and bound a workspace, the Agent form starts offering Star Harness.

Execution model

StageOwnerSource
Model / tool loopHarness native kernelowner: 'ksadk-harness', execution: 'native-kernel'
Contract with Studioagentkit.native-dsh-turn/v1contract
Event sourcenative-run-storeeventOwner
Streamingnative-model-portstreamOwner
Capabilitiesnative-run, durable-receipts, tool-approval, cancel, resume, child-taskscapabilities

Source: src/runtime-contract.mjs:25-29.

DSH supplies the whole-turn port (host contract dsh.external-turn-host/v1) and hands control to the Harness engine once per turn (dsh.external-turn/v1). Before taking over, the Harness package verifies the host exposes claim, pending and resume (native/dsh-turn-ownership.mjs:47-52 in @kingsoftcloud/agentkit-harness-node).

It cannot use the ordinary stream seam

In local mode, harness passing through DSH's stream adapter throws STUDIO_NATIVE_TURN_REQUIRED ("Native Harness requires the whole-turn execution port."). It must be served by the whole-turn port; it cannot be treated as one more model stream (src/providers/dsh-runtime.mjs:591).

Dependency direction

Studio depends on three Harness npm packages, pinned exactly:

PackageVersionPurpose
@kingsoftcloud/agentkit-harness-core0.0.25Canonical values, invariants, kernel primitives
@kingsoftcloud/agentkit-harness-node0.0.25Whole-turn contract, Run ownership, package integrity
@kingsoftcloud/agentkit-harness-ui0.0.25Engine view adapter

Source: package.json:133-135 (all three pinned, with no ^ or ~).

Harness does not depend on Studio. None of the three packages lists a @kingsoftcloud/agentkit-studio* entry in its dependencies — the dependency is one-way, so upgrading Harness does not require a Studio release.

Installation and lifecycle

Star Harness is driven by the "Star Harness management" section of the plugin page, and its five operations map onto five control endpoints:

OperationEndpointUI text
Read statusstar-harness/statusInstalled <version> / Not installed, with "enabled / disabled"
Install / upgradestar-harness/install"Install", "Upgrade", "Reinstall"
Enable / disablestar-harness/enable"Enable", "Disable"
Bind workspacestar-harness/bind"Bind workspace"
Unbindstar-harness/unbind"Unbind"

Source: src/host/routes/star-harness.mjs:7-11, src/remote/control-client.mjs:469-473, src/client/pages/star-harness.mjs:64-112.

Version rules

RuleBehaviourSource
Version formatMust be three numeric segments x.y.zsrc/host/services/star-harness-release.mjs:14-15
Upgrade or roll back onlyA target that is neither newer nor the previous version → STAR_HARNESS_VERSION_UNSUPPORTEDsrc/host/services/star-harness.mjs:186-191
RollbackA "Roll back to <version>" button appears when previousVersion existssrc/client/pages/star-harness.mjs:88
Release verificationOnly versions the current Studio has verified; otherwise STAR_HARNESS_RELEASE_UNREVIEWEDsrc/host/services/star-harness-release.mjs:22-28
Package integrityPer-file digests verified; dependency resolution may not escape the install directory:32-59
RegistryPinned to https://registry.npmjs.org:12

Why versions are verified first

Studio confirms the Harness version was verified by the running Studio before installing it. Changing the Harness version changes a dependency pin, not Studio source — but an unverified version is refused outright instead of being installed and failing later.

Workspace bindings

One workspace maps to one model profile and its own isolated runtime state:

RuleBehaviourSource
Absolute path requiredA non-canonical absolute path → STAR_HARNESS_INVALID_REQUESTsrc/host/services/star-harness.mjs:212-217
No overlapOverlap with an existing binding, the Star Harness state directory or an external Harness route → STAR_HARNESS_WORKSPACE_CONFLICT:71-72, :214-215
Model must be availableThe selected model profile must exist and be enabled:216-217
Model driftA changed model after binding → STAR_HARNESS_MODEL_CHANGED; rebind:61-64
Missing directoryA deleted workspace shows "directory no longer valid" and stops routingsrc/client/pages/star-harness.mjs:97, src/host/services/star-harness.mjs:132

When to choose it

  • You need cross-process resume (resume): of the three runtimes, only Star Harness has it.
  • You need child tasks (child-tasks) and durable receipts (durable-receipts): multi-role task decomposition depends on both.
  • You need tool approval as a first-class runtime capability (tool-approval).
  • You already run DeepSeek Harness and want the whole turn handed to the Harness kernel instead of the DSH native loop.

When none of these apply, DSH Native is simpler — see runtime comparison.

Limits

LimitEffectSource
It must be installed before it can be selectedOnly "installed + enabled + at least one workspace" lets you create a new Agentsrc/client/pages/agent-form.mjs:79, src/host/services/star-harness.mjs:162、:174
Not installedEnabling or binding before installing throws STAR_HARNESS_NOT_INSTALLEDsrc/host/services/star-harness.mjs:14
No bound workspaceEnabling without a usable workspace → NATIVE_ENGINE_WORKSPACE_UNAVAILABLE:15
No changes while busyA running task or in-flight change → STAR_HARNESS_BUSY:11
One writer per ledgerThe new worker takes over only after the old one stops; a failed cutover restores the previous version:95-125
Versions are pinned exactlyAll three packages are 0.0.25, with no floating rangepackage.json:133-135
No standalone persistence entryDurability is offered as durable-receipts, a different implementation from DSH's persistencesrc/runtime-contract.mjs:27

Star Harness and DSH Native own different Run ledgers

Switching a runtime does not migrate Run history: old sessions keep opening on their original runtime. Star Harness Runs belong to the Harness ledger, while DSH Native Runs belong to the DSH session.

Failure shapes

CodeTriggerWhat you can do
STAR_HARNESS_NOT_INSTALLEDEnabling or binding before installingInstall a verified version first
STAR_HARNESS_RELEASE_UNREVIEWEDThe requested version is not verified by this StudioUpgrade Studio, or pick a verified version
STAR_HARNESS_VERSION_UNSUPPORTEDThe target is neither newer nor the previous versionPick a newer version, or roll back
STAR_HARNESS_WORKSPACE_CONFLICTThe workspace overlaps an existing binding or the state directoryUse a non-overlapping absolute path
STAR_HARNESS_MODEL_CHANGEDThe bound model profile changedRebind that workspace
STAR_HARNESS_BUSYA task is running or a change is in flightWait for the task, then change version or bindings
STAR_HARNESS_CONFIG_INVALIDThe local settings file cannot be readInspect settings.json in the Star Harness state directory
NATIVE_ENGINE_WORKSPACE_UNAVAILABLEThe workspace is unbound or disabledBind and enable the workspace first
STUDIO_NATIVE_TURN_REQUIREDharness reached the ordinary stream seamCheck whether the Host offers the whole-turn port; usually a DSH baseline mismatch
STAR_HARNESS_UNSUPPORTEDThe deployment is administrator-managed and offers no local managementContact your administrator

Degradation and retry when a resource is unavailable is in degradation and retry.

Source of truth

ClaimLocation
Capability matrix and ownershipsrc/runtime-contract.mjs:25-29
Whole-turn port requirementsrc/providers/dsh-runtime.mjs:591
Host capability checknative/dsh-turn-ownership.mjs:47-52 in agentkit-harness-node
Management service and state machinesrc/host/services/star-harness.mjs:21-251
Version verification and package integritysrc/host/services/star-harness-release.mjs:14-61
Control endpointssrc/host/routes/star-harness.mjs:7-11
Client interactionsrc/client/pages/star-harness.mjs:64-112
Creatability gatesrc/client/pages/agent-form.mjs:61-79
Three packages pinnedpackage.json:133-135

On this page