AgentKit Studio
Runtimes and deployment

DSH Native Harness

The default runtime's execution model, when to choose it, where its configuration lives, its hard limits, and what you see when it fails.

DSH Native Harness (dsh-native) hands the loop to DSH itself; Studio only translates on both sides. DSH keeps the Session and the conversation renderer, and Studio turns the assembled request into one model stream and writes the result back as DSH text chunks (src/providers/dsh-runtime.mjs:4-9).

Execution model

StageOwnerSource
Request assemblyDSH native loopsrc/runtime-contract.mjs:21
Model callStudio's provider bridgesrc/providers/dsh-runtime.mjs:5-9
Tool executionDSH native ToolRegistrysrc/providers/dsh-runtime-plugin.mjs
Session and transcriptDSH SessioneventOwner: 'dsh-session'
Streaming framesdsh-agent/assistant-streamstreamOwner
Route identityagentkit-studiosrc/providers/dsh-runtime.mjs:33

A request travels: DSH session dispatch → Studio preset scope → Agent request event → model stream → DSH text chunks. Studio keeps no second tool loop and does not retry native side effects.

When to choose it

  • Choose it when you have no specific reason not to. It is the default authoring runtime (src/authoring-defaults.mjs:4) and the only path that needs neither an extra process nor an external service.
  • You want native DSH session behaviour: history reload, archive, search and the native list all work directly.
  • You need native request replay (replay): only the DSH side can rebuild routing from native request headers.
  • Expert and team sessions must run on native DSH Agent Teams.

Do not choose it when you need cross-process resume (resume) or child tasks (child-tasks); neither is in its capability set (src/runtime-contract.mjs:22).

Configuration entry points

SettingWhereNotes
Runtime typeCreate / edit Agent → runtime radio groupSelected by default; the option reads "local native loop, uses tools and resources on demand" (src/client/pages/agent-form.mjs:9)
Model and credentialsSettings → Models and credentialsCredentials stay on the Host side and are never echoed into the form
Tool / MCP / Skill bindingsCreate / edit Agent → capability bindingsCreating with DSH Native clears previously selected tools (src/client/pages/agent-form.mjs:83)
Execution policyPolicy and confirmation stepread-only / workspace-write / danger-full-access, default workspace-write (src/execution-policy.mjs:8-10)
{
  "spec": {
    "runtime": { "type": "dsh-native" },
    "bindings": { "modelProfileId": "your-model-profile" }
  }
}

Limits

LimitEffectSource
No resumeAfter a process restart you cannot resume from an arbitrary Run checkpoint; only session history reload is availablesrc/runtime-contract.mjs:22
No child-tasksChild tasks come from native DSH Agent Teams, not from the runtimesame
Requires real Host capabilitiesA missing execution contract is refused outright instead of falling back to a model interceptorsrc/runtime-contract.mjs:29-30
Frozen Builds have an outer deadline15 minutes by default, tunable via AGENTKIT_RUNTIME_TIMEOUT_MS (1000–86400000 ms)src/frozen-build-runtime.mjs:19-25
Runtime version must matchThe installed DSH version must equal the version declared by the Studio packagerequiredDsh in studio.plugin.json

The frozen runtime follows the DSH scope

The configured frozen runtime starts and stops with its native dependency scope: replacing a dependency closes the old runtime and starts a new one once dependencies are available. A startup that finishes after the scope is disposed closes its listener immediately (src/host/frozen-runtime-lifecycle.mjs:4-19).

How to confirm you are on DSH Native

CheckExpected valueSource
Agent definitionspec.runtime.type === 'dsh-native'src/authoring-defaults.mjs:4
Agent list badgeShows DSH Native Harness with the accent tonesrc/client/theme.mjs:29, src/client/pages/overview.mjs:81
Editing an existing AgentKeeps its original runtime; dsh-native is only the fallback when no definition existssrc/client/pages/agent-form.mjs:48
Session historyServed by the native DSH list; selecting an Agent never filters historyNo Studio-side filter extension

Clearing tools on create is deliberate

Creating an Agent on DSH Native clears previously selected tools (src/client/pages/agent-form.mjs:83). That keeps a stale binding from a prior edit out of a brand-new native loop; editing an existing Agent does not trigger it.

Migrating back from another runtime

  • Editing never changes the runtime on its own. Opening an existing Agent takes initialRuntime from originalSpec.runtime.type and only falls back to the default when it is missing (src/client/pages/agent-form.mjs:48).
  • Star Harness and Codex own different Run ledgers. Switching to dsh-native does not migrate existing Run history; old sessions keep opening on their original runtime.

Failure shapes

CodeTriggerWhat you can do
RUNTIME_UNSUPPORTEDruntime.type is not one of the three runtimesCheck spec.runtime.type in the Agent definition
RUN_IDENTITY_INVALIDagentId / sessionId / runId / buildId missing, or revision is not a positive integerRe-select the Agent or reopen the app
RUN_IDENTITY_MISMATCHThe identity disagrees with the Agent / Session bound to the routeClose and reopen that session; never reuse it across sessions
STUDIO_HOST_INCOMPATIBLEThe Host lacks a required execution contractUpgrade to the matching DSH baseline; management routes stay available
STUDIO_PRESET_RESOURCES_UNAVAILABLEA bound resource failed to recover under strict modeFix the binding and retry, or turn off AGENTKIT_STRICT_RESOURCES
STUDIO_PRESET_SCOPE_CLOSEDA callback arrives after the preset scope retiredReopen the session; the plugin may be reloading

The full degradation and retry rules live in degradation and retry.

Source of truth

ClaimLocation
DSH owns the loop, Studio only translatessrc/providers/dsh-runtime.mjs:4-9
Route constantsrc/providers/dsh-runtime.mjs:33
Capability set and event sourcesrc/runtime-contract.mjs:20-24
Default authoring runtimesrc/authoring-defaults.mjs:4
Execution policy enumsrc/execution-policy.mjs:8-11
Frozen runtime lifetimesrc/host/frozen-runtime-lifecycle.mjs:1-19
Frozen runtime deadlinesrc/frozen-build-runtime.mjs:19-25

On this page