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.
| Constant | Value | Meaning |
|---|---|---|
STUDIO_RUNTIME_CONTRACT_VERSION | agentkit.studio.runtime/v1 | Contract version and admission gate |
STUDIO_RUNTIME_TYPES | dsh-native · harness · codex | Publicly routable runtime types |
STUDIO_CANONICAL_IDENTIFIERS | agentId · revision · buildId · sessionId · runId | Identifier 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.type | owner | execution | contract | capabilities | eventOwner | streamOwner |
|---|---|---|---|---|---|---|
dsh-native | dsh | native | agentkit.studio.runtime/v1 | session session-events stream cancel replay persistence build-binding | dsh-session | dsh-agent/assistant-stream |
harness | ksadk-harness | native-kernel | agentkit.native-dsh-turn/v1 | native-run durable-receipts tool-approval cancel resume child-tasks | native-run-store | native-model-port |
codex | studio | codex-app-server | studio.codex.adapter/v1 | session stream cancel replay build-binding | studio-codex-adapter | codex-turn/item |
Entities and identifiers
Six entities share one identifier vocabulary. A missing layer means an invalid identity.
| Entity | Fields |
|---|---|
Agent | id→agentId · revision→revision |
Revision | id→revision · parent→agentId |
Build | id→buildId · agent→agentId · revision→revision |
Session | id→sessionId · build→buildId · agent→agentId · revision→revision |
Run | id→runId · session→sessionId · build→buildId · agent→agentId · revision→revision |
Validation errors
| Code | Trigger | Source |
|---|---|---|
RUNTIME_UNSUPPORTED | runtime.type is neither public nor experimental | src/runtime-contract.mjs:67 |
RUN_IDENTITY_INVALID | agentId / sessionId / runId / buildId missing, or revision is not a positive integer | src/runtime-contract.mjs:74 |
RUN_IDENTITY_MISMATCH | Run identity disagrees with the bound route | src/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
| Item | Value | Notes |
|---|---|---|
| Contract version | agentkit.studio.runtime/v1 | Evolves in the same PR as the Studio version |
| Public runtimes | 3 | dsh-native / harness / codex |
| Identifier fields | 5 | Renaming one is a breaking change |
Developer entry points
| Item | Source |
|---|---|
| Runtime contract | src/runtime-contract.mjs |
| Session event vocabulary | src/host/dsh-session-contract.mjs |
| Native turn contract | packages/harness/src/native/dsh-turn-contract.ts |
Related tests:
| Test file | Location |
|---|---|
| runtime-contract.test.mjs | tests/runtime-contract.test.mjs |
| runtime-registry.test.mjs | tests/runtime-registry.test.mjs |