AgentKit Studio
Ecosystem and plugins

Host compatibility

How Studio decides whether the current DSH host can run a capability — five probes, three feature gates, baseline comparison, and the admission error code.

Before executing any native capability, Studio asks the host who it is. No answer means refused — no guessing, no silent degradation.

Admission checks three dimensions; all must pass:

DimensionComparedVariable
BaselineWhether the running DSH version is exactly equal to the manifestrequiredDsh
ContractWhether the compatibility contract version matchesrequiredHostContract
CapabilitiesWhether the declared methods exist on host servicescapabilities

Source: src/host/compatibility.mjs:15-33.

Manifest declarations

{
  "requiredDsh": "0.2.2-rc.1",
  "requiredHostContract": 1,
  "capabilities": [
    "studio.agent.catalog",
    "studio.runtime.capabilities",
    "studio.session.adapter",
    "studio.workspace.dock"
  ]
}

The baseline comes from studio.plugin.json; the actual version comes from DSH's public boot API getDshRuntimeVersion(). Source: src/host/compatibility.mjs:53-71.

Display versions cannot authorize execution

AGENTKIT_STUDIO_DSH_VERSION only affects what the UI shows. Setting it to the expected value does not make a capability pass — the real version can only be read from the running DSH package. Unreadable means incompatible. Source: src/host/compatibility.mjs:55-62.

The five capability probes

Capability idWhat is probedPasses when
preset-compositionAgent preset registryagentPresets.register and agentPresets.pluginsFor are functions
agent-loop-originRequest origin detectionisAgentLoopRequest is a function
session-controllerSession controllercreate/selectModel/resolveAgent/prompt/page/projections
automation-policyAutomation policy gateagents.withoutInitiator + permissionPresets.set + approval.setPolicy
request-fingerprintRequest fingerprintingpromptFingerprintVersion === 1 and prompt is a function

Each probe returns 1 (present) or 0 (missing). Source: src/host/compatibility.mjs:18-24.

Probes never create sessions

inspect() only reads service shapes — it does not call create, does not send requests, does not write disk. Calling it repeatedly is safe, and it must be repeated: a previous Host or registry generation cannot vouch for a replacement. Source: src/host/compatibility.mjs:12-14.

The three feature gates

FeatureRequired capabilitiesUsed for
agent-presetspreset-composition + agent-loop-originSelecting an agent preset and composing it into a session
automationThe two above + session-controller + automation-policyAutomation and scheduling
frozen-runtimeThe four above + request-fingerprintFrozen runtime request budgets and replay

Features are cumulative over capabilities: frozen-runtime needs all five. Source: src/host/compatibility.mjs:5-9.

The inspection result

const report = hostCompatibility.inspect();
// {
//   baseline: { required: '0.2.2-rc.1', actual: '0.2.2-rc.1', compatible: true },
//   contract: { required: 1, actual: 1, compatible: true },
//   capabilities: { 'preset-composition': 1, 'agent-loop-origin': 1, ... },
//   features: {
//     'agent-presets': { available: true, requiredCapabilities: {...}, missingCapabilities: [] },
//     ...
//   }
// }
FieldMeaning
baseline.compatibleResult of a string equality check; actual being null means incompatible
contract.compatibleContract numbers are equal
features[x].availableBaseline and contract and no missing capabilities
features[x].missingCapabilitiesWhich capability ids are missing

Source: src/host/compatibility.mjs:25-32.

When admission fails

Any failed feature gate throws the same error:

{
  "code": "STUDIO_HOST_INCOMPATIBLE",
  "status": 503,
  "message": "Studio frozen-runtime is unavailable: request-fingerprint. Install the compatible Studio Host.",
  "details": {
    "status": 503,
    "feature": "frozen-runtime",
    "baseline": { "required": "0.2.2-rc.1", "actual": "0.2.1-rc.2", "compatible": false },
    "contract": { "required": 1, "actual": 1, "compatible": true },
    "missingCapabilities": []
  }
}

Three refusal reasons

Fragment in messageMeaningFix
DSH baselineVersions are not equalBring DSH to the version declared in requiredDsh
compatibility contractContract numbers differUpgrade the Studio plugin to a version matching the contract
Comma-separated capability idsService methods missingHost version is right but services are not mounted — check that every plugin loaded

Source: src/host/compatibility.mjs:34-43.

Querying from outside

Entry pointNotes
host/compatibility operationReturns the current result; requires authentication
window.__AGENTKIT_STUDIO__.hostCompatibilityThe same result injected into the browser document
hostCompatibility.inspect()Direct call inside the Host process

Neither external entry exposes credentials, filesystem paths, or session content. Source: src/index.mjs:31-45, docs/host-compatibility.md.

Startup vs execution

MomentBehaviour
Host startupComputes compatibility once and injects it into the browser document
Before native executionEach feature re-checks via require(feature); a Host may restart services or swap registries, so the startup verdict goes stale
Unknown feature nameThrows TypeError: Unknown Studio Host feature: <name>

Source: src/host/compatibility.mjs:34-37.

Troubleshooting checklist

node -p "require('./studio.plugin.json').requiredDsh"   # baseline declared by the manifest
node -p "require('./dsh-pin.json').version"             # version pinned at packaging
node -e "import('@deepseek-ai/dsh-app-boot').then(m => console.log(m.getDshRuntimeVersion?.()))"
SymptomCauseFix
The first two lines disagreePackaging used the wrong manifestRe-align studio.plugin.json and dsh-pin.json
The third line prints undefinedThe DSH boot package is absentNo native capability is available; repair the DSH install
missingCapabilities is non-emptyHost version is right but services are not mountedLook the method up in the five-probe table and check that the official plugin is enabled
Display version is right but admission failsOnly AGENTKIT_STUDIO_DSH_VERSION was changedDisplay versions do not participate in authorization — see the callout above

The DSH baseline and the other version numbers live in version compatibility, manifest fields in DSH plugin authoring, and every error code in the error reference.

On this page