AgentKit Studio
Reference

Runtime and entity contract

The 3 runtimes, capability matrix, entity identifiers and validation codes of `agentkit.studio.runtime/v1`.

Contract version

The runtime contract has exactly one version constant: agentkit.studio.runtime/v1. It gates the Agent form, portable runtime bundles and deployments alike.

ConstantValueMeaning
STUDIO_RUNTIME_CONTRACT_VERSIONagentkit.studio.runtime/v1Contract version and admission gate
STUDIO_RUNTIME_TYPESdsh-native · harness · codexPublicly routable runtime types
STUDIO_CANONICAL_IDENTIFIERSagentId · revision · buildId · sessionId · runIdIdentifier field names shared by every entity

There are 3 public runtimes: dsh-native, harness, codex. assertStudioRuntimeType() accepts only these and rejects everything else with RUNTIME_UNSUPPORTED. Adding a runtime only changes src/runtime-contract.mjs:STUDIO_RUNTIME_TYPES; this page's count and capability matrix follow automatically. See runtimes.

Capability matrix

Every runtime declares its owner, execution model, event and stream contract. Combinations outside this matrix are unsupported.

runtime.typeownerexecutioncontractcapabilitieseventOwnerstreamOwner
dsh-nativedshnativeagentkit.studio.runtime/v1session session-events stream cancel replay persistence build-bindingdsh-sessiondsh-agent/assistant-stream
harnessksadk-harnessnative-kernelagentkit.native-dsh-turn/v1native-run durable-receipts tool-approval cancel resume child-tasksnative-run-storenative-model-port
codexstudiocodex-app-serverstudio.codex.adapter/v1session stream cancel replay build-bindingstudio-codex-adaptercodex-turn/item

Entities and identifiers

Six entities share one identifier vocabulary. A missing layer means an invalid identity.

EntityFields
Agentid→agentId · revision→revision
Revisionid→revision · parent→agentId
Buildid→buildId · agent→agentId · revision→revision
Sessionid→sessionId · build→buildId · agent→agentId · revision→revision
Runid→runId · session→sessionId · build→buildId · agent→agentId · revision→revision

Validation errors

CodeTriggerSource
RUNTIME_UNSUPPORTEDruntime.type is neither public nor experimentalsrc/runtime-contract.mjs:67
RUN_IDENTITY_INVALIDagentId / sessionId / runId / buildId missing, or revision is not a positive integersrc/runtime-contract.mjs:74
RUN_IDENTITY_MISMATCHRun identity disagrees with the bound routesrc/runtime-contract.mjs:88

studioRunIdentity() normalizes before validating, so a blank string equals a missing field; revision is coerced to a number.

Version and compatibility

ItemValueNotes
Contract versionagentkit.studio.runtime/v1Evolves in the same PR as the Studio version
Public runtimes3dsh-native / harness / codex
Identifier fields5Renaming one is a breaking change

Developer entry points

ItemSource
Runtime contractsrc/runtime-contract.mjs
Session event vocabularysrc/host/dsh-session-contract.mjs
Native turn contractpackages/harness/src/native/dsh-turn-contract.ts

Related tests:

Test fileLocation
runtime-contract.test.mjstests/runtime-contract.test.mjs
runtime-registry.test.mjstests/runtime-registry.test.mjs

On this page