Interactive Session API: schemas
The request and response bodies of the operations in this API.
AttachSkillDto
Type: object
AttachWorkspaceActionDto
| Property | Type | Required | Description |
|---|
action | one of "attach" | yes | Discriminator: attach an existing workspace. |
workspaceId | string | yes | |
AttachedSkillDto
| Property | Type | Required | Description |
|---|
attachedBy | string | yes | Actor that attached it. |
createdAt | string | yes | When it was attached, ISO-8601. |
description | string | yes | Skill description at attach time. |
failure | SkillAttachmentFailureDto | no | Present with status = failed. A skill_content_mismatch kind means the skill changed under the pin: re-attach to pick up the new revision. |
id | string | yes | Attachment id. |
name | string | yes | Display name at attach time. |
skillSlug | string | yes | Slug of the attached skill. |
status | SkillAttachmentStatus | yes | Where the attachment is relative to the worker's bound skill set: pending and detach_pending are in flight, bound is on the worker, failed carries failure. |
AttachedSkillDtoDataArrayEnvelope
AttachedSkillDtoDataEnvelope
AttachmentClass
Type: one of "uploaded_file"
AttachmentResponseDto
| Property | Type | Required | Description |
|---|
attachmentClass | AttachmentClass | yes | |
contentType | string or null | no | |
createdAt | string (date-time) | yes | |
fileName | string or null | no | |
fileSizeBytes | number or null | no | |
id | string | yes | |
objectKey | string or null | no | |
referenceId | string or null | no | |
sessionId | string | yes | |
status | SessionAttachmentStatus | yes | Uploaded files transition pending_upload → ready after the SAS upload-complete step succeeds. |
uploadedAt | string (date-time) or null | no | Set when the row transitioned to ready (upload-complete). |
url | string or null | no | |
AttachmentResponseDtoDataArrayEnvelope
AttachmentResponseDtoDataEnvelope
AttachmentUploadInitResponseDto
| Property | Type | Required | Description |
|---|
attachmentId | string | yes | Draft attachment row id. Pass to POST /sessions/:id/attachments/:attachmentId/upload-complete. |
expiresAt | string (date-time) | yes | Absolute timestamp when the SAS stops being accepted. |
objectKey | string | yes | Object key the SAS is bound to. Returned for diagnostics; the browser does NOT need to set it — the URL already points at the right blob. |
requiredHeaders | map of string | yes | Headers the browser MUST send on the PUT verbatim. |
uploadUrl | string | yes | Presigned PUT URL the browser uploads the bytes to. |
AttachmentUploadInitResponseDtoDataEnvelope
BranchStrategy
Type: one of "auto_create", "use_existing", "none"
BranchThreadDto
| Property | Type | Required | Description |
|---|
title | string | no | Branch title. Defaults to a title derived from the parent. |
BuildImageResultDto
| Property | Type | Required | Description |
|---|
digest | string | yes | Resolved image manifest digest (sha256:…). |
durationMs | number | yes | Wall-clock duration of the Kaniko build in milliseconds. |
imageRef | string | yes | Fully qualified <registry>/<repo>:<tag> reference. |
BuildImageStartedResponseDto
| Property | Type | Required | Description |
|---|
imageRef | string | yes | Image reference the workflow will push to on success — <registry>/<orgId>/<projectId>:sha-<short>. Surfaced up-front so the FE can show what the build is producing. |
runId | string | yes | Temporal run id assigned to this execution. |
sha | string | yes | SHA the build is anchored on (full git SHA of the primary repo HEAD). |
workflowId | string | yes | Deterministic Temporal workflow id — build:<sessionId>:<sha>. |
BuildImageStartedResponseDtoDataEnvelope
BuildImageStatusResponseDto
| Property | Type | Required | Description |
|---|
failureMessage | object or null | no | Failure detail — present only on terminal-failure statuses. Null otherwise. Surfaced verbatim to the FE toast. |
result | BuildImageResultDto or null | no | Resolved image — present only when status === COMPLETED. Null while running or on failure. |
runId | string | yes | |
status | string (10 values) | yes | |
workflowId | string | yes | |
BuildImageStatusResponseDtoDataEnvelope
CommitDto
| Property | Type | Required | Description |
|---|
message | string | yes | Commit message |
CompactSessionDto
| Property | Type | Required | Description |
|---|
threadId | string | no | Thread whose conversation to compact. Must belong to the session. Defaults to the session's default thread. |
CreateBranchDto
| Property | Type | Required | Description |
|---|
baseBranch | string | no | Base branch to create from (default: current HEAD) |
branchName | string | yes | Branch name to create |
CreateLaunchDefinitionDto
| Property | Type | Required | Description |
|---|
slug | string | yes | |
CreateSandboxSessionDto
| Property | Type | Required | Description |
|---|
launch | SessionLaunchBodyDto | yes | |
mockTools | boolean | no | When true, this sandbox runs against the mcp-gateway test-mode MOCK tool bridge — tool calls return canned responses instead of hitting live MCP services. Default false (live tools). |
toolMocks | array of SandboxToolMockDto | no | Optional per-tool canned mock responses to register for this sandbox at create time. Supplying a non-empty array implies mockTools = true — the sandbox runs against the mcp-gateway test-mode mock bridge. Equivalent to a follow-up PUT /sessions/sandbox/{id}/tool-mocks call. |
ttlMinutes | number | no | Sandbox lifetime in minutes (default 30, max 240). A periodic sweeper disposes the sandbox once the TTL elapses. |
CreateSessionDto
| Property | Type | Required | Description |
|---|
approvalResume | SessionApprovalResumeDto | no | |
internetEgressCeiling | WorkerInternetEgress | no | Optional narrowing of whether this session's workspace pod may open sockets to the public internet. Tighten-only and pinned for the session's life. Absent states nothing. |
invocationOverlay | object | yes | Strict kernel InvocationOverlay v2; unknown keys are rejected. |
launchDefinition | SessionRevisionTargetDto | yes | |
runtimeProfile | SessionRuntimeProfileChoiceDto | no | Optional choice among the runtime profiles the launch definition admits. Absent: the launch definition's pinned default runtime profile (declared behaviour). Frozen for the session's life. |
sessionDomain | SessionDomainDto | no | The domain object this session is launched FOR. When present, the caller must hold the object's edit relation (a PDP verdict on the object, never a check of what the request says); relation states whether the object contains the session or is only referred to. Absent ⇒ a session for no domain object. |
title | string | no | |
workspace | NoWorkspaceActionDto or AttachWorkspaceActionDto or CreateWorkspaceActionDto | yes | Workspace action. Discriminated on action. |
CreateThreadDto
| Property | Type | Required | Description |
|---|
title | string | no | Thread title. Defaults to "New thread" when omitted. |
CreateWorkspaceActionDto
| Property | Type | Required | Description |
|---|
action | one of "create" | yes | Discriminator: allocate a new workspace for this session. |
backing | SessionWorkspaceBackingDto | yes | |
displayName | string | yes | |
slug | string | yes | |
CreateWorkspaceBackingDto
CreateWorkspaceDto
| Property | Type | Required | Description |
|---|
hasMore | boolean | yes | Whether another page exists. Mandatory for cursor pagination (§3.3). |
limit | number | no | The page size this scan was asked for. |
nextCursor | string or null | yes | Opaque continuation token, or null on the last page. Clients MUST NOT parse it, construct one, or derive meaning from its structure. |
DeliverableReactionPhase
The phase this validation reacted in.
Type: one of "live", "checkpoint"
DeliverableValidationIssueDto
| Property | Type | Required | Description |
|---|
code | string | yes | Stable machine code of the defect. |
message | string | yes | The validator's own words; can quote file content. |
path | string or null | yes | The deliverable path the issue is about, when it has one. |
severity | DeliverableValidationIssueSeverity | yes | |
DeliverableValidationIssueSeverity
Type: one of "warning", "error"
DeliverableValidationUnavailableReason
Type: one of "peer_not_deployed", "peer_refused", "authority_unavailable", "peer_response_unreadable", "verdict_pending", "workspace_unreadable", "check_failed"
DomainLaunchAccessResponseDto
| Property | Type | Required | Description |
|---|
allowed | boolean | yes | True when the caller holds the edit relation a launch for the object requires. |
DomainLaunchAccessResponseDtoDataEnvelope
EnvironmentDriftDetectedPayloadDto
| Property | Type | Required | Description |
|---|
currentHash | string | yes | Hash of the freshly-resolved environment snapshot. |
drifts | array of EnvironmentDriftEntryDto | yes | Per-field diff between previous and current snapshot. |
previousHash | string | yes | Hash of the previously-recorded environment snapshot. |
EnvironmentDriftEntryDto
| Property | Type | Required | Description |
|---|
after | object | no | Value at the current snapshot. Omitted when the field was removed. |
before | object | no | Value at the previous snapshot. Omitted when the field did not exist before. |
kind | string | yes | Drift category (e.g. "tool_added", "tool_removed", "model_changed"). |
path | string | yes | Dotted path identifying the changed field within the environment snapshot. |
severity | string | yes | Severity tier reported by the bootstrap drift detector. |
ExactRevisionSelectorDto
| Property | Type | Required | Description |
|---|
contentHash | string | yes | |
kind | one of "exact" | yes | Discriminator: an already-immutable revision pin. |
revisionId | string | yes | |
ForkSessionDto
| Property | Type | Required | Description |
|---|
title | string | no | Title for the forked session (defaults from the parent). |
FrameProminence
Whether a quiet client shows the event: primary (the primary agent's answer, the asks a user must answer and their settlement, the primary agent's plan, the turn outcome) or secondary (sub-agent activity, tool calls and results, reasoning, usage, file and LSP activity, internal lifecycle). Present only on an event a runtime frame produced; absent on every other event (user messages, status, git, attachments) and on events written before this field existed. A quiet filter hides only secondary.
Type: one of "primary", "secondary"
GitCommitEntryDto
| Property | Type | Required | Description |
|---|
authorEmail | string | yes | |
authorName | string | yes | |
date | string | yes | |
hash | string | yes | |
message | string | yes | |
GitCommitEntryDtoDataArrayEnvelope
GitCommitResponseDto
| Property | Type | Required | Description |
|---|
commitHash | string | yes | |
message | string | yes | |
GitCommitResponseDtoDataEnvelope
GitStatusResponseDto
| Property | Type | Required | Description |
|---|
added | array of string | yes | |
branch | string | yes | |
deleted | array of string | yes | |
modified | array of string | yes | |
repos | array of RepoGitStatusDto | yes | Per-repository status — one entry per /workspace/repos/<slug>/. |
untracked | array of string | yes | |
GitStatusResponseDtoDataEnvelope
HookBindingReadinessDto
| Property | Type | Required | Description |
|---|
bindingId | string | yes | Opaque binding id; quote it to an administrator. |
reasonCode | HookBindingReadinessReason | no | Present iff state is not ready. |
required | boolean | yes | Whether a failure of this binding fails the tool call. |
spaceKind | SpaceKind | yes | The tier of the Space the binding lives in (set by your organization, project or you). |
state | HookBindingReadinessState | yes | |
HookBindingReadinessReason
Present iff state is not ready.
Type: one of "receiver-refused", "fan-out-skipped", "execute-authority-unauthorized", "execute-authority-unprovisioned", "execute-authority-ended", "receiver-check-unavailable"
HookBindingReadinessState
Type: one of "ready", "failing-closed", "skipped", "unknown"
HookEvaluationFailureCause
Why the evaluation failed as a whole; present only when outcome is failed.
Type: one of "projection-unavailable", "scope-refused", "recursion", "fan-out-saturated", "phase-failed", "receiver-refused", "timeout"
HookFailureCode
The kernel failure code of that binding.
Type: string (10 values)
HookFeedReadinessDto
| Property | Type | Required | Description |
|---|
state | HookProjectionState | yes | State of this replica's projection of the binding registry. Anything but synced fails evaluations closed. |
syncedAt | string (date-time) or null | yes | When this replica last proved the projection current; null if never. |
HookMode
Type: one of "admit", "transform", "defer", "respond"
HookPhase
Type: one of "transform", "validate", "respond"
HookPointReadinessDto
HookPointReadinessReason
Present iff state is not ready.
Type: one of "not-realized-by-runtime", "projection-unavailable", "scope-refused", "fan-out-saturated", "required-binding-not-ready", "receiver-check-unavailable", "optional-binding-not-ready"
HookPointReadinessState
Type: one of "unenforced", "failing-closed", "degraded", "ready"
HookPointRealization
How the point reaches this session's tool calls.
Type: one of "runtime", "unrealized"
HookProjectionState
State of this replica's projection of the binding registry. Anything but synced fails evaluations closed.
Type: one of "synced", "unhydrated", "stale", "revision-mismatched", "failed"
InitAttachmentUploadDto
| Property | Type | Required | Description |
|---|
contentType | string | yes | MIME type of the file. Pinned into the SAS — the browser MUST send the PUT request with exactly this Content-Type header or the upload fails. |
fileName | string | yes | Original filename — extension drives the allowed-file check. |
fileSizeBytes | number | yes | File size in bytes. Verified against the blob HEAD on complete. |
InspectStepResultDto
| Property | Type | Required | Description |
|---|
data | object | no | |
error | string | no | |
kind | string (15 values) | yes | |
status | one of "ok", "error", "timeout", "page-navigated", "off-domain", "skipped", "output-surface-not-open" | yes | |
InvitableParticipantRole
Role to assign. owner is not invitable — ownership is set at session-create time (one per session).
Type: one of "editor", "viewer"
InviteParticipantDto
| Property | Type | Required | Description |
|---|
avatarUrl | string | no | |
displayName | string | yes | |
role | InvitableParticipantRole | yes | Role to assign. owner is not invitable — ownership is set at session-create time (one per session). |
subjectRef | string | yes | Keycloak user id (Xema identity) of the user being invited. The capability-router grant check uses this as the subject ref. |
LaunchDefinitionDraftResponseDto
| Property | Type | Required | Description |
|---|
baseRevisionId | string or null | yes | |
content | object | yes | |
draftId | string | yes | |
resourceId | string | yes | |
restoredFromRevisionId | string or null | yes | |
updatedAt | string (date-time) | yes | |
updatedBy | SubjectRefResponseDto | yes | |
LaunchDefinitionDraftResponseDtoDataArrayEnvelope
LaunchDefinitionDraftResponseDtoDataEnvelope
LaunchDefinitionIdentityFieldsResponseDto
LaunchDefinitionLaunchability
Whether this definition can be launched, and when it cannot, why. Present on EVERY row. Do NOT re-derive it from an absent presentation: that absence has two causes — nothing published, and nothing promoted — which need different actions from the reader, and a derived predicate labels a rolled-back definition "unpublished" to the person who published it.
Type: one of "launchable", "not-promoted", "never-published"
LaunchDefinitionListItemResponseDto
| Property | Type | Required | Description |
|---|
identity | LaunchDefinitionIdentityFieldsResponseDto | yes | |
launchability | LaunchDefinitionLaunchability | yes | Whether this definition can be launched, and when it cannot, why. Present on EVERY row. Do NOT re-derive it from an absent presentation: that absence has two causes — nothing published, and nothing promoted — which need different actions from the reader, and a derived predicate labels a rolled-back definition "unpublished" to the person who published it. |
pointers | LaunchDefinitionPointersResponseDto | yes | |
presentation | LaunchDefinitionPresentationResponseDto | no | |
presentationRevisionId | string | no | Which revision supplied presentation, so its provenance is visible. It is the revision on the stable release channel — the one a launch resolves — and NOT the newest by sequence. |
LaunchDefinitionListItemResponseDtoDataArrayEnvelope
LaunchDefinitionPointersResponseDto
| Property | Type | Required | Description |
|---|
draftId | string or null | yes | |
resourceId | string | yes | |
LaunchDefinitionPresentationResponseDto
| Property | Type | Required | Description |
|---|
iconRef | string | no | |
label | string | yes | |
summary | string | no | |
surfaces | array of LaunchSurfaceKind | yes | |
LaunchDefinitionReleaseHistoryResponseDto
| Property | Type | Required | Description |
|---|
actorClientId | string | yes | |
channel | one of "stable" | yes | |
channelVersion | number | yes | |
createdAt | string (date-time) | yes | |
operation | one of "promote", "rollback", "retire" | yes | |
reason | string | yes | |
releaseSetId | string | yes | |
retired | boolean | yes | |
rollbackOfReleaseSetId | string | no | |
target | LaunchDefinitionReleaseTargetResponseDto | yes | |
LaunchDefinitionReleaseHistoryResponseDtoDataArrayEnvelope
LaunchDefinitionReleaseSelectorResponseDto
| Property | Type | Required | Description |
|---|
contentHash | string (sha256) | yes | |
kind | one of "exact" | yes | |
revisionId | string | yes | |
LaunchDefinitionReleaseTargetResponseDto
LaunchDefinitionRescopeTarget
Target owner tier. org is the only legal target — it is the only one the kernel promotion table admits from a tier this registry owns. Demotion, same-tier, and moves into or out of system/biome are refused with 422.
Type: one of "org"
LaunchDefinitionResponseDto
LaunchDefinitionResponseDtoDataEnvelope
LaunchDefinitionRevisionResponseDto
| Property | Type | Required | Description |
|---|
content | object | yes | |
contentHash | string (sha256) | yes | |
createdAt | string (date-time) | yes | |
createdBy | SubjectRefResponseDto | yes | |
idempotencyKey | string | yes | |
resourceId | string | yes | |
restoredFromRevisionId | string or null | yes | |
revisionId | string | yes | |
sequence | number | yes | |
LaunchDefinitionRevisionResponseDtoDataArrayEnvelope
LaunchDefinitionRevisionResponseDtoDataEnvelope
LaunchRevisionSelectorKind
Type: one of "exact", "release-channel"
LaunchRuntimeProfileOptionDto
LaunchRuntimeProfilesResponseDto
LaunchRuntimeProfilesResponseDtoDataEnvelope
LaunchSurfaceKind
Type: one of "web", "portal", "conversation-channel"
ListSessionParticipantsResponseDto
ListSessionParticipantsResponseDtoDataEnvelope
MemberSubjectKind
Discriminator of the authoring subject — a Xema user. An external-contact author is stamped only by an organization session's holder workload, never stated by a caller.
Type: one of "org_user"
MergeCheckResponseDto
| Property | Type | Required | Description |
|---|
conflicts | array of string | yes | Files with merge conflicts (empty when mergeable is true) |
mergeable | boolean | yes | Whether the session branch can merge cleanly into the target |
MergeCheckResponseDtoDataEnvelope
MessageResponseDto
| Property | Type | Required | Description |
|---|
actor | SessionMessageActorDto or null | yes | Who wrote this message. null for agent-authored roles (the agent is agentSlug) and for messages written before attribution existed. |
agentSlug | string | yes | |
content | string | yes | |
createdAt | string (date-time) | yes | |
id | string | yes | |
metadata | object or null | no | Free-form metadata: tool traces, model attribution, token accounting. Shape varies per producer. Consumers must treat unknown keys defensively. |
role | SessionMessageRole | yes | |
sessionId | string | yes | |
threadId | string | yes | Conversation thread this message belongs to |
MessageResponseDtoPaginatedEnvelope
NoWorkspaceActionDto
| Property | Type | Required | Description |
|---|
action | one of "none" | yes | Discriminator: launch without a workspace. |
OutputSurfaceAppResponseDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | |
externalUrl | string or null | no | Public share URL (https://{token}.{apex}/). Present while the app is registered with the gateway. |
id | string | yes | |
installCommand | string or null | no | Exact install command that ran (or will run), space-joined. |
installEcosystem | string or null | no | Package manager / ecosystem that drove the last install step. Present when status is installing / install_failed / running (install already ran). |
installStderrTail | string or null | no | Truncated stderr tail captured on install failure. Populated only when status=install_failed. |
kind | ProjectKind | yes | |
lastError | string or null | no | |
lastExitCode | number or null | no | |
name | string | yes | |
openApiPath | string or null | no | |
port | number or null | no | |
repoSlug | string | yes | |
sessionId | string | yes | |
status | OutputSurfaceAppStatus | yes | |
tokenGeneration | number | yes | |
updatedAt | string | yes | |
OutputSurfaceAppResponseDtoDataArrayEnvelope
OutputSurfaceAppResponseDtoDataEnvelope
OutputSurfaceAppStatus
Type: one of "detected", "declaration_needed", "installing", "install_failed", "starting", "running", "crashed", "stopped"
Which remediation widget raised this — drives template selection.
Type: one of "install_error", "declaration_missing", "declaration_invalid", "runtime_error"
OutputSurfaceRestartMode
Type: one of "smart", "restart_only", "reinstall"
OwnerSpaceRefResponseDto
| Property | Type | Required | Description |
|---|
fence | one of "global", "tenant" | yes | |
orgId | string or null | yes | |
space | SpaceRefResponseDto | yes | |
| Property | Type | Required | Description |
|---|
hasMore | boolean | no | |
limit | number | no | |
nextCursor | string or null | no | |
page | number | no | |
previousCursor | string or null | no | |
total | number | no | |
totalPages | number | no | |
ParticipantRole
Role inside this session. Closed set.
Type: one of "owner", "editor", "viewer"
ParticipantSubjectKind
Discriminator on subjectRef. Closed set: org_user is a Xema identity; external_contact is a person reached through a conversation channel.
Type: one of "org_user", "external_contact"
ProblemActionableBy
Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.
Type: one of "user", "org-admin", "platform", "none"
ProblemDetailsDto
RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.
| Property | Type | Required | Description |
|---|
actionableBy | ProblemActionableBy | no | Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed. |
code | string | yes | SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name. |
detail | string | no | Human-readable and specific to THIS occurrence. |
errors | array of ProblemFieldIssueDto | no | Field-level issues, when the refusal is about the request body. |
instance | string | no | URI reference identifying the occurrence — a request path, a run, a row. |
params | map of string or number or boolean | no | Safe i18n interpolation values for the message keyed by code — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics. |
retry | ProblemRetry | no | What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known. |
status | number | yes | The HTTP status code, repeated in the body so a logged document is self-contained. |
title | string | yes | Short, human-readable, and STABLE for a given type. Never per-occurrence — that is detail. |
traceId | string | no | W3C trace-context trace-id, present when the caller sent a traceparent. Omitted rather than invented when it did not. |
type | string | yes | Absolute URI identifying the refusal TYPE. Derived one-to-one from code, so a caller may branch on either and can never be told two different things. Never about:blank. |
ProblemFieldIssueDto
| Property | Type | Required | Description |
|---|
code | string | no | SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem. |
detail | string | yes | Prose for logs and developers. A frontend localises from code + params instead. |
params | map of string or number or boolean | no | Safe i18n interpolation values for this issue's code. |
pointer | string | yes | RFC 6901 JSON Pointer into the request body. Root is "/". |
ProblemRetry
What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.
Type: one of "transient", "after-change", "never"
ProjectKind
Type: string (14 values)
PublishLaunchDefinitionDto
| Property | Type | Required | Description |
|---|
content | object | yes | |
expectedDraftId | string | yes | |
idempotencyKey | string | yes | |
PublishLaunchDefinitionResponseDto
PublishLaunchDefinitionResponseDtoDataEnvelope
ReasoningDeltaPayloadDto
| Property | Type | Required | Description |
|---|
text | string | yes | Incremental reasoning fragment from the assistant thinking stream. |
ReleaseChannelRevisionSelectorDto
| Property | Type | Required | Description |
|---|
channel | string | yes | |
kind | one of "release-channel" | yes | Discriminator: unresolved authoring intent; the owning authority resolves it to an exact pin before execution. |
| Property | Type | Required | Description |
|---|
outputSurfaceAppId | string | yes | Database id of the SessionOutputSurfaceApp row (cuid). The same id the FE receives from GET /sessions/:id/output-surfaces/apps. NOT the workspace-proxy worker-side ${repoSlug}:${name} form. |
remediationKind | OutputSurfaceRemediationKindInput | yes | Which remediation widget raised this — drives template selection. |
| Property | Type | Required | Description |
|---|
outputSurfaceAppId | string | yes | Database id of the SessionOutputSurfaceApp row the remediation was dispatched for. Echoes the request value. |
templateId | string | yes | Stable identifier of the prompt template that was rendered and injected. |
ReplyToQuestionDto
| Property | Type | Required | Description |
|---|
answers | array of array of string | yes | Per-question-part answers — one inner array of selected option strings per part. |
RepoGitStatusDto
| Property | Type | Required | Description |
|---|
added | array of string | yes | |
branch | string | yes | |
deleted | array of string | yes | |
modified | array of string | yes | |
path | string | yes | Path relative to /workspace |
primary | boolean | yes | Whether this is the primary repo |
role | RepoRole | yes | Repository role |
slug | string | yes | Repository slug |
targetBranch | string | yes | Target branch for merge/PR |
untracked | array of string | yes | |
RepoRole
Repository role
Type: one of "DELIVERABLE", "REFERENCE"
ReportInspectPresenceDto
| Property | Type | Required | Description |
|---|
bridgeInstanceId | string | no | Identifier of the bridge instance on the current page. |
kind | one of "attach", "heartbeat", "detach", "hello", "unloading" | yes | |
outputSurfaceOrigin | string | no | |
reason | one of "navigation", "off-domain" | no | Only meaningful for kind=unloading. |
targetUrl | string | no | Best-effort off-domain target URL (kind=unloading). |
title | string | no | |
url | string | no | |
ReportInspectResultDto
RescopeLaunchDefinitionDto
| Property | Type | Required | Description |
|---|
targetScope | LaunchDefinitionRescopeTarget | yes | Target owner tier. org is the only legal target — it is the only one the kernel promotion table admits from a tier this registry owns. Demotion, same-tier, and moves into or out of system/biome are refused with 422. |
RestoreLaunchDefinitionRevisionDto
| Property | Type | Required | Description |
|---|
expectedDraftId | string or null | yes | |
ResumeSessionDto
| Property | Type | Required | Description |
|---|
agentSlugOverride | string | no | Replacement primary agent slug. Provided only when recovering a session whose original agent was removed — switches the session's primary agent before resuming. Lowercase kebab-case. |
RetireLaunchDefinitionDto
Type: object
RollbackLaunchDefinitionDto
| Property | Type | Required | Description |
|---|
priorReleaseSetId | string | yes | |
RotateTokenResponseDto
| Property | Type | Required | Description |
|---|
externalUrl | string | yes | New stable share URL. Previous URL is now invalid. |
tokenGeneration | number | yes | |
RotateTokenResponseDtoDataEnvelope
RunSandboxEvalTurnDto
| Property | Type | Required | Description |
|---|
prompt | string | yes | The realistic user prompt to send to the sandbox agent. |
RuntimeAuthMode
Type: one of "brokered"
RuntimeProfileAvailability
Type: one of "available", "account-required", "not-admitted"
SandboxEvalTurnResultDto
| Property | Type | Required | Description |
|---|
durationMs | number | yes | End-to-end turn duration in milliseconds. |
output | string | yes | The agent’s final assistant reply text for the turn. |
sessionId | string | yes | The sandbox session id. |
threadId | string | yes | The thread the turn ran on. |
totalTokens | number | yes | Sum of input + output tokens across every step of the turn (0 when the runtime emitted no step-token accounting). |
SandboxEvalTurnResultDtoDataEnvelope
| Property | Type | Required | Description |
|---|
isError | boolean | no | When true, the canned result is flagged as a tool error. Default false. |
response | string | yes | Canned result body returned in the single MCP text content block when the agent calls this tool inside the sandbox. |
toolName | string | yes | Canonical MCP tool name this mock answers for. |
| Property | Type | Required | Description |
|---|
mockedToolNames | array of string | yes | Canonical tool names that currently have a registered mock. |
sessionId | string | yes | The sandbox session id. |
SaveLaunchDefinitionDraftDto
| Property | Type | Required | Description |
|---|
content | object | yes | |
expectedDraftId | string or null | yes | |
SessionApprovalResumeDto
| Property | Type | Required | Description |
|---|
decisionId | string | yes | |
evidenceHash | string | yes | |
policyRequestId | string | yes | |
producerRef | string | yes | |
SessionArtifactDto
| Property | Type | Required | Description |
|---|
artifactType | SessionArtifactType | yes | Deterministic content kind derived from the file extension. |
content | string | yes | The deliverable file body, inlined. Empty string when the file exceeded the per-file read cap (see truncated). Consumers render this directly — it is NOT a URL or blob pointer. |
id | string | yes | Stable identifier for this artifact within the session — the workspace-relative path of the deliverable file (e.g. deliverables/contract.json). Unique per session. |
schemaVersion | string | no | Schema version parsed from the artifact body when it is a JSON manifest carrying a top-level schemaVersion field. Absent for non-manifest deliverables. |
sizeBytes | number | yes | Total byte length of the deliverable file on the worker, before any read-cap truncation. |
title | string | yes | Human-readable title — the deliverable file name (e.g. contract.json). |
truncated | boolean | yes | True when the file exceeded the per-file read cap and content is therefore empty or partial. The frontend surfaces this so a large deliverable is never silently shown as empty. |
SessionArtifactDtoDataArrayEnvelope
SessionArtifactType
Deterministic content kind derived from the file extension.
Type: one of "markdown", "json", "yaml", "text"
SessionAttachmentStatus
Uploaded files transition pending_upload → ready after the SAS upload-complete step succeeds.
Type: one of "pending_upload", "ready", "upload_failed"
SessionAttendance
Whether a human answers what this session's runtime asks, fixed at launch from the door that admitted it and never changed. attended (a browser or shell launch) = a runtime permission or question opens a decision for a person. unattended (an API, workflow, schedule or agent launch) = every runtime permission is denied and every question rejected at once, with an interaction_answered_unattended event, and no decision is opened.
Type: one of "attended", "unattended"
SessionBlobAttachmentDto
| Property | Type | Required | Description |
|---|
contentType | string | yes | |
downloadUrl | string | yes | Short-lived presigned GET URL the workspace-proxy uses to fetch the blob directly. Bearer-via-URL — never log it. |
id | string | yes | |
relPath | string | yes | |
requiredHeaders | map of string | yes | Headers the fetcher MUST send verbatim. Empty for Azure SAS. |
sizeBytes | number | yes | |
SessionBlobAttachmentDtoDataArrayEnvelope
SessionContentPinDto
| Property | Type | Required | Description |
|---|
contentHash | string | yes | |
ref | string | yes | Opaque immutable resource/deployment reference. |
SessionContextWindowSnapshotDto
| Property | Type | Required | Description |
|---|
cacheReadTokens | number | yes | Cache-read tokens (count toward context-window usage). |
cacheWriteTokens | number | yes | Cache-creation tokens (count toward context-window usage). |
inputTokens | number | yes | Input tokens of the most recent assistant turn. |
modelId | string or null | no | Model id that produced this snapshot. Used by the FE to look up the right contextWindow divisor even if the user re-pinned the session after the turn ended. |
outputTokens | number | yes | Output tokens of the most recent assistant turn. |
providerId | string or null | no | Provider that produced this snapshot. Null when no per-turn override was supplied (worker fell back to the agent default — the FE then uses the session's current model to look up the context window). |
updatedAt | string | yes | ISO timestamp of the upstream OpenCode step_finished event. |
SessionDebugAgentNodeDto
| Property | Type | Required | Description |
|---|
agentSlug | string | yes | Agent slug at this node. |
depth | number | yes | Tree depth — 0 is the root (primary agent). |
modelOverride | string or null | no | Per-node model override resolved from the composition, when one is pinned. |
skillSlugs | array of string | yes | Skill slugs attached at this node. |
SessionDebugInfoDto
| Property | Type | Required | Description |
|---|
activatedSkills | array of SessionDebugSkillDto | yes | Skills currently mounted into the session, with attach provenance. |
agentReference | string or null | no | Agent reference. For a standard session this is the published slug@version; for a sandbox session this is the draft Agent row id under test. |
compositionTree | array of SessionDebugAgentNodeDto | yes | The resolved composition tree (primary agent + sub-agent tree, per-node model + skills). |
gaps | array of string | yes | Honest list of debug data that is NOT obtainable without deeper instrumentation (e.g. exact prompt token footprint). Empty when every block resolved fully. |
injectedContextSkillSlugs | array of string | yes | Injected-context view: the slugs of skills + metadata loaded into the agent context. Token footprint is NOT surfaced here — see gaps. |
kind | SessionKind | yes | Session kind. |
mountPlan | object or null | no | The projected mount plan / WorkspaceSpec from the last resolved environment snapshot. Null until the session has booted once (the bootstrap path persists the first snapshot). |
primaryModelDecision | SessionDebugModelDecisionDto or null | no | Model Resolution Matrix decision trace for the primary agent — which rule won and why. Null when llm-registry-api could not be reached. |
sessionId | string | yes | Session id. |
SessionDebugInfoDtoDataEnvelope
SessionDebugModelDecisionDto
| Property | Type | Required | Description |
|---|
matchedDimensions | array of string | yes | Dimensions the winning rule matched on. |
matchedRuleId | string or null | no | Id of the Model Resolution Matrix rule that won; null = implicit default fallback. |
modelId | string | yes | Resolved concrete model id. |
overridden | boolean | yes | True when a run/realtime override pre-empted the matrix. |
providerSlug | string or null | no | Resolved provider slug. |
reason | string | yes | Human-readable win reason. |
SessionDebugSkillDto
| Property | Type | Required | Description |
|---|
attachedAt | string | yes | When the skill was attached (ISO 8601). |
attachedBy | string | yes | Actor id that attached the skill. |
attachedByType | string | yes | Who attached it — composition-default, a human actor, or another agent. |
slug | string | yes | Skill slug. |
snapshot | object or null | no | Skill metadata snapshot captured at attach time (name, description, source path). |
SessionDeliverableAcceptanceVerdict
The verdict of the final validation at handoff.
Type: one of "accepted", "refused", "unavailable"
SessionDeliverableFinalValidationDto
SessionDeliverableReactionValidationDto
SessionDeliverableValidationStatus
Type: one of "invalid", "incomplete", "complete", "pending", "unavailable"
SessionDeliverableValidationsDto
SessionDeliverableValidationsDtoDataEnvelope
SessionDomainDto
| Property | Type | Required | Description |
|---|
bindingInputs | map of string | no | Values the domain object's owner supplies for the session's ${input.<name>} working-file interpolation (for example a record's layout and format). Replaced later only by the service that writes the object's authorization facts. |
key | string | yes | The domain object's authorization type (for example <biome>_<type>). |
ref | string | yes | The domain object's id within the organization. |
relation | SessionDomainRelation | yes | How the session relates to the object, stated by the launcher; never inferred and never defaulted. parent: the object is the session's authorization parent and governs who may read it. reference: context only; it widens no read and the session has no parent. Required whenever a domain object is given. |
SessionDomainRelation
How the session relates to the object, stated by the launcher; never inferred and never defaulted. parent: the object is the session's authorization parent and governs who may read it. reference: context only; it widens no read and the session has no parent. Required whenever a domain object is given.
Type: one of "parent", "reference"
SessionExactResourcePinDto
| Property | Type | Required | Description |
|---|
contentHash | string | yes | Lowercase SHA-256 of the immutable revision bytes. |
resourceId | string | yes | |
revisionId | string | yes | |
SessionExecutionMode
Whether this session ever gets a worker. worker = a pod, a volume and an allocation are provisioned for it. hosted = its agent loop runs in-service; it never allocates a worker, and that is a FINAL, READY state rather than a stage on the way to one. Derive this from nothing else: workspaceId, projectId and status are each a proxy that answers for a different axis, and a project-scoped session whose author chose backing: none holds a workspace and is hosted. A client showing worker-warmup affordances (a 'tools still loading' chip, a file browser, a terminal) must gate on this field — worker-bound operations answer 409 SESSION_WORKER_NOT_APPLICABLE for a hosted session, and retrying cannot change that.
Type: one of "hosted", "worker"
SessionHookReadinessDto
| Property | Type | Required | Description |
|---|
bindingSetRevision | number or null | yes | Binding-set revision of this replica's projection; null when it is not synced. |
evaluatedAt | string (date-time) | yes | |
feed | HookFeedReadinessDto | yes | |
points | array of HookPointReadinessDto | yes | |
sessionId | string | yes | The session this readiness was evaluated for. |
SessionHookReadinessDtoDataEnvelope
SessionKind
Session kind.
Type: one of "standard", "sandbox"
SessionLaunchApprovalDto
| Property | Type | Required | Description |
|---|
decisionId | string | yes | |
decisionRevision | number | yes | |
decisionStatus | string | yes | |
evidenceHash | string | yes | |
policyRequestId | string | yes | |
producerRef | string | yes | |
SessionLaunchBodyDto
SessionLaunchOutcome
Type: one of "created", "approval_required"
SessionLaunchResponseDto
SessionLaunchResponseDtoDataEnvelope
SessionLockfileDto
| Property | Type | Required | Description |
|---|
agents | map of string | no | Map of agent slug to chosen published semver. Optional. |
biomes | map of string | yes | Map of biome slug to the chosen published semver. |
capabilities | map of string | yes | Map of capability ref (sans @major) to the chosen major version string. |
deliverableSpecs | map of string | no | Map of deliverable-spec slug to chosen published semver. Optional. |
kernel | string | yes | Resolved kernel semver string at the moment the session was created. |
skills | map of string | no | Map of skill slug to chosen published semver. Optional. |
workflows | map of string | no | Map of workflow slug to chosen published semver. Optional. |
SessionLockfileDtoDataEnvelope
SessionMessageActorDto
| Property | Type | Required | Description |
|---|
avatarUrl | string | no | Avatar rendered on the message bubble. |
displayName | string | yes | Name rendered on the message bubble. |
subjectKind | ParticipantSubjectKind | yes | Discriminator on subjectRef. Closed set: org_user is a Xema identity; external_contact is a person reached through a conversation channel. |
subjectRef | string | yes | Opaque per-kind reference to the author. |
SessionMessageRole
Type: one of "user", "assistant", "system", "tool"
SessionParticipantDto
| Property | Type | Required | Description |
|---|
avatarUrl | string | no | |
displayName | string | yes | |
id | string | yes | Participant row id. |
invitedAt | string | yes | ISO-8601 timestamp of the invite. |
invitedBy | string | yes | Subject ref of the inviter. |
lastSeenAt | string | no | ISO-8601 timestamp of the last message this participant posted on the session. Null until they post their first message. |
role | ParticipantRole | yes | Role inside this session. Closed set. |
sessionId | string | yes | Session this participant belongs to. |
subjectKind | MemberSubjectKind | yes | Discriminator on subjectRef. Closed set — org_user is a Xema-identity user (Keycloak sub). |
subjectRef | string | yes | Opaque per-kind reference. org_user: Keycloak user id. |
SessionParticipantDtoDataEnvelope
SessionPauseReason
Why the session left active for paused. user = explicit pause (needs an explicit resume); allocation_lost = the worker allocation was reaped out-of-band and the next user interaction auto-resumes; worker_replaced = the worker pod was replaced under the same allocation (its runtime state is gone) and the next user interaction auto-resumes. Frontend distinguishes user from the others so the user only sees the "resume required" affordance when their action is actually required.
Type: one of "user", "allocation_lost", "worker_replaced"
SessionPermissionGrantDto
| Property | Type | Required | Description |
|---|
createdAt | string (date-time) | yes | When the grant was recorded. |
decisionId | string | yes | The decision whose "Always allow" answer is the grant of record. |
grantedBy | string | yes | Canonical subject ref of the human whose "Always allow" commit is the grant. |
id | string | yes | Grant id; pass it to the revoke route. |
permission | string | yes | The runtime permission the grant answers "allow" for (e.g. edit, bash). |
resource | string | yes | The resource the grant covers, verbatim; matched by exact string equality only. |
SessionPermissionGrantDtoDataArrayEnvelope
SessionProvisioningPhase
Fine-grained, monotonic provisioning phase. The launch path records worker launch, credential injection, configuration, workspace preparation, worker readiness, and the terminal ready or failed outcome. Complements the coarse status field.
Type: string (9 values)
SessionResolvedCapabilityDto
| Property | Type | Required | Description |
|---|
authorityEffect | string or null | no | |
descriptorHash | string | yes | |
effectClass | string | yes | |
externalServiceRef | string or null | no | |
reach | string | yes | |
ref | string | yes | |
SessionResolvedCompositionProofDto
SessionResponseDto
| Property | Type | Required | Description |
|---|
agentRef | string or null | yes | OPAQUE pinned identity — <agentResourceId>@<agentRevisionId>, both cuids. DO NOT PARSE IT AND DO NOT RESOLVE IT. Read the pin from resolvedComposition.agent instead, which carries the same two ids as separate typed fields (resourceId, revisionId) plus the content hash, and resolve with GET /agents/revisions/:revisionId/resolved. This field is NOT accepted by GET /agents/resolve/:ref: that route parses the half after @ with /^[1-9]\d*$/ — a positive INTEGER revision number — so a cuid answers 400, measured in production on 2026-09-15. Nor is it a slug@version, which this description claimed until that date; the producer writes ${composition.agentRevision.resourceId}@${composition.agentRevision.revisionId} (session-launch.service.ts), and primary-agent-slug.ts has said so all along. Even if it parsed, resolving a ref with no revision returns the LATEST published revision, while the session stays pinned to the one it composed against — so a resolvable ref would describe an Agent the session is not running. Null for a sandbox session (it resolves its DRAFT composition by sandboxAgentId) or a session created before the Phase 6 cutover backfill. |
agentSlug | string | yes | Internal agent slug resolved from profile |
attendance | SessionAttendance | yes | Whether a human answers what this session's runtime asks, fixed at launch from the door that admitted it and never changed. attended (a browser or shell launch) = a runtime permission or question opens a decision for a person. unattended (an API, workflow, schedule or agent launch) = every runtime permission is denied and every question rejected at once, with an interaction_answered_unattended event, and no decision is opened. |
branchName | string or null | no | |
branchStrategy | BranchStrategy | yes | |
budgetLimit | number or null | no | |
completedAt | string or null | no | |
contextWindowSnapshot | SessionContextWindowSnapshotDto or null | no | Latest OpenCode context-window snapshot, mirrored from the most recent usage frame and reset to zeros on session.compacted. Null until the first turn completes — the composer chip stays hidden in that window because we cannot honestly report the system-prompt size before any usage lands. |
createdAt | string (date-time) | yes | |
createdBy | string | yes | |
executionMode | SessionExecutionMode | yes | Whether this session ever gets a worker. worker = a pod, a volume and an allocation are provisioned for it. hosted = its agent loop runs in-service; it never allocates a worker, and that is a FINAL, READY state rather than a stage on the way to one. Derive this from nothing else: workspaceId, projectId and status are each a proxy that answers for a different axis, and a project-scoped session whose author chose backing: none holds a workspace and is hosted. A client showing worker-warmup affordances (a 'tools still loading' chip, a file browser, a terminal) must gate on this field — worker-bound operations answer 409 SESSION_WORKER_NOT_APPLICABLE for a hosted session, and retrying cannot change that. |
failureCode | string or null | no | Stable, machine-readable failure code paired with failureReason when the failure has structured recovery info. Frontend branches on this to render code-specific UX (e.g. REPO_EMPTY → "push your first commit"). null when the failure was unstructured (transport, timeout) — fall back to failureReason. |
failureMetaJson | object or null | no | Structured payload paired with failureCode. Shape is code-specific. For clone failures: { slug, requestedBranch, availableBranches, defaultBranchSuggestion }. |
failureReason | string or null | no | Human-readable reason the session moved to failed status |
handoffAt | string or null | no | When the handoff arrived. Mirrors handoffOutput presence. |
handoffOutput | object or null | no | Structured deliverable contract emitted by the in-session agent (the JSON written to /workspace/deliverables/contract.json against the session's deliverableSpecRef). Captured idempotently on the first POST /sessions/:id/handoff. null until the agent has handed off. |
id | string | yes | Session identifier (cuid) |
jobRunId | string or null | no | Workflow-engine job-run id that spawned this session. Only meaningful when pipelineRunId is also set — together they let the workflow-runtime worker route the eventual handoff signal back to the right job-level promise. |
lastActivityAt | string (date-time) | yes | |
modelId | string or null | no | |
modelSelection | object or null | no | Current model selection override. Either a ConcreteModelRef {kind: "concrete", modelId, providerSlug?, temperature?} or a StrategyModelRef {kind: "strategy", modelLane, temperature?}. Null = no override; the agent's default modelLane strategy cascade resolves the model per prompt. |
opencodeProviders | array of string | yes | Model routes (provider slugs) bound to the session at launch or by a later bind. The FE picker uses this to decide whether a model switch names a bound route (served directly) or one the session lacks (refused). Empty array before the first bind applies. |
orgId | string | yes | Owning organization ID (Keycloak group ID) |
parentSessionId | string or null | no | Reference to the session this one was forked from (via POST /sessions/:id/fork). Stamped server-side from the URL; API clients cannot forge parentage. Null for sessions created directly. |
pauseBlockedAttempts | number | yes | Consecutive failed pause attempts in the current streak. 0 when the session is not failing to pause. Reset when the session leaves active. |
pauseBlockedEscalatedAt | string or null | no | Set once, when the failed-pause streak crossed the escalation threshold — i.e. this session now needs a HUMAN. Non-null is the flag a UI should render on: the session cannot persist its work and is holding a worker against the org concurrency quota. It is NOT a terminal state and the platform does not give up: retries continue every idle-monitor tick, and the first one that succeeds clears all four pauseBlocked* fields. |
pauseBlockedReason | string or null | no | The most recent pause failure of the current streak, truncated. This is the attribution: an unreachable SCM remote, an expired credential and a Temporal outage are different fixes. |
pauseBlockedSince | string or null | no | When this session first FAILED to pause in the current streak; null whenever it is not failing to pause. A pause is fail-fast on purpose — for a git-push slot the SCM remote is the only storage, so pausing over a failed push would release the worker and destroy the working tree. The platform therefore keeps the session active and RETRIES, rather than force-pausing. This timestamp is how long that has been going on; the work is still intact on the worker throughout. |
pauseCausedByRuntimeLoss | boolean | yes | True only when the session is paused because it lost its runtime: the worker allocation was lost (allocation_lost) or the worker was replaced (worker_replaced). False for a user or idle pause and whenever the session is not paused. It says why the session paused, not whether a message resumes it (a message wakes any paused session). Derived from the server-side rule, so clients never hard-code the set of reasons. |
pauseReason | SessionPauseReason or null | no | Why the session left active for paused. user = explicit pause (needs an explicit resume); allocation_lost = the worker allocation was reaped out-of-band and the next user interaction auto-resumes; worker_replaced = the worker pod was replaced under the same allocation (its runtime state is gone) and the next user interaction auto-resumes. Frontend distinguishes user from the others so the user only sees the "resume required" affordance when their action is actually required. |
pausedAt | string or null | no | |
pipelineRunId | string or null | no | Pipeline run that owns this session (set when the session is created by a pipeline-run request). Sourced from RequestContext, never client-supplied. |
prUrl | string or null | no | |
preferredModelLane | string or null | no | Per-session "smartness" preference — a Model Resolution Matrix modelLane MATCHED dimension (NOT an above-rules override, unlike modelSelection). When set, the send path resolves the turn model with this class as the matched modelLane dimension, so a managed org's tier rules CLAMP it (a user can never reach a model outside their tier); an unmapped class falls through to the org default; a BYOK org resolves directly. An explicit modelSelection pin WINS over this softer preference. Closed set: coding | review | creative | planning | utility. Null = the agent's native modelLane (today's behavior). |
projectId | string or null | yes | Project this session belongs to. null for a project-less session — such a session is project-less by construction (it may still hold a project-keyed provisioning; project is switchable context inside the conversation instead). |
provisioningFailureHint | string or null | no | Human-readable hint attached when provisioning fails; null while still in progress or on success. |
provisioningPhase | SessionProvisioningPhase | yes | Fine-grained, monotonic provisioning phase. The launch path records worker launch, credential injection, configuration, workspace preparation, worker readiness, and the terminal ready or failed outcome. Complements the coarse status field. |
provisioningPhaseSince | string (date-time) | yes | Timestamp the session entered the current provisioningPhase. Used by UIs to render per-phase elapsed time. |
repositoryId | string or null | no | |
resolvedComposition | SessionResolvedCompositionProofDto | yes | |
resolvedConfigHash | string or null | no | |
runtimeImageRef | string or null | no | Fully-pinned runtime image the session is running on RIGHT NOW — the repo@sha256:… coordinate the workspace-orchestrator resolved for the session's current allocation. Re-stamped on every cold resume, because a resume deliberately comes back on the CURRENT digest rather than the one the session launched with, so this can differ from the image it started on. null before the first allocation, for rows that predate the column, and when an allocation reported no ref (recorded as absent rather than guessed). Read it together with status: a paused session is running nothing, and the value then names the LAST image it ran. Reporting only — no client may use it to request an image, and nothing in the platform places against it. |
sessionDomainKey | string or null | no | Biome-owned domain key attached to this session runtime. Null means generic interactive session. |
sessionDomainRef | string or null | no | Opaque domain row identifier associated with sessionDomainKey (for example the id of a <biome>_<type> object when sessionDomainKey names that type). |
status | SessionStatus | yes | |
title | string or null | no | Human-readable session title set at creation or inherited from profile |
tokenUsage | SessionTokenUsageDto or null | no | |
toolSelection | array of object | yes | ALWAYS EMPTY. Shape is ToolSelectionEntry[] from @xemahq/kernel-contracts/mcp-tool, but nothing writes the underlying column, so every session reports []. This description previously said the value is "updated via PATCH /sessions/:id/tools" — no such route exists on any surface of this service, and none ever has. Do not branch on this field: what a session may invoke is decided by the capability plane (grants, the agent aperture, its AgentReachTier ceiling), never by a per-session tool list. |
updatedAt | string (date-time) | yes | |
workspaceId | string or null | no | Canonical Workspace identity attached for this Session; null when the session holds no workspace at all. This does NOT tell you whether a worker exists — a session may hold a workspace whose backing is none. Read executionMode for that. |
SessionResponseDtoDataEnvelope
SessionResponseDtoPaginatedEnvelope
SessionRevisionTargetDto
SessionRuntimeProfileChoiceDto
| Property | Type | Required | Description |
|---|
resourceId | string | yes | resourceId of a RuntimeProfile the launch definition admits |
SessionStatus
Type: string (9 values)
SessionTimelineEntryDto
| Property | Type | Required | Description |
|---|
createdAt | string | yes | When the row was inserted (ISO 8601). Use sequence for ordering, not this — it is the row-write time, not the producer-occurrence time. |
eventType | string (66 values) | yes | Closed-set event type emitted by the session. |
id | string | yes | Per-row id (cuid). |
payload | TextDeltaPayloadDto or ReasoningDeltaPayloadDto or EnvironmentDriftDetectedPayloadDto or ToolCallPayloadDto or object | yes | Event payload. Shape depends on eventType: text_delta / reasoning_delta carry TextDeltaPayload / ReasoningDeltaPayload; environment_drift_detected carries EnvironmentDriftDetectedPayload; tool_call_started / tool_call_completed carry ToolCallPayload. Every other event type carries a free-form object payload — switch on eventType and treat unknown variants as opaque. |
prominence | FrameProminence | no | Whether a quiet client shows the event: primary (the primary agent's answer, the asks a user must answer and their settlement, the primary agent's plan, the turn outcome) or secondary (sub-agent activity, tool calls and results, reasoning, usage, file and LSP activity, internal lifecycle). Present only on an event a runtime frame produced; absent on every other event (user messages, status, git, attachments) and on events written before this field existed. A quiet filter hides only secondary. |
sequence | number | yes | Per-session monotonic sequence assigned by SessionEventAppender. Strictly increasing within a session, with no gaps. Use this as the cursor for ?afterSequence=. |
threadId | string | yes | Conversation thread this event belongs to. |
SessionTimelinePageDto
| Property | Type | Required | Description |
|---|
entries | array of SessionTimelineEntryDto | yes | |
nextAfterSequence | number or null | yes | Cursor for the next page. Pass back as afterSequence to resume. null when no more rows. |
SessionTimelinePageDtoDataEnvelope
SessionTokenUsageDto
| Property | Type | Required | Description |
|---|
inputTokens | number | yes | |
outputTokens | number | yes | |
| Property | Type | Required | Description |
|---|
bindingSetRevision | number or null | yes | The binding-set revision the call was evaluated under; null only when the evaluation threw before it had one. |
decidedAt | string (date-time) | yes | |
denials | array of ToolDenialDto | yes | The refusing bindings; empty when failed. |
failureCause | HookEvaluationFailureCause | no | Why the evaluation failed as a whole; present only when outcome is failed. |
failures | array of ToolDenialFailureDto | yes | The failed bindings; empty when denied. |
hookPoint | string | yes | The hook point that ruled (agent-session.tool.execute). |
id | string | yes | Record id. |
outcome | SessionToolDenialOutcome | yes | denied: a binding refused the call. failed: the evaluation failed closed. |
sessionId | string | yes | |
toolName | string | yes | Name of the tool the call was for. Arguments are never recorded. |
denied: a binding refused the call. failed: the evaluation failed closed.
Type: one of "denied", "failed"
SessionWorkingFileDto
| Property | Type | Required | Description |
|---|
acceptsUserEdits | boolean | yes | Whether the file takes user edits (bidirectional); only such a file has working-file user-edits and resync routes. |
format | one of "markdown", "html", "json", "yaml", "text" | yes | |
object | WorkingFileObjectDto or null | yes | The domain object this file is bound to, or null when the file is not backed by an object (a one-way file, or a session with no domain binding). |
path | string | yes | Path of the file inside the session workspace. |
slug | string | yes | The working file's slug; the key of its user-edits and resync routes. |
syncDirection | one of "down-only", "up-only", "bidirectional" | yes | |
SessionWorkingFileDtoDataArrayEnvelope
SessionWorkspaceBackingDto
| Property | Type | Required | Description |
|---|
toolMocks | array of SandboxToolMockDto | yes | The mocked tools to register for this sandbox session. |
SkillAttachmentFailureDto
| Property | Type | Required | Description |
|---|
kind | string | yes | Typed failure kind (a session failure code). |
message | string | yes | Human-readable text; never contains a secret. |
SkillAttachmentStatus
Where the attachment is relative to the worker's bound skill set: pending and detach_pending are in flight, bound is on the worker, failed carries failure.
Type: one of "pending", "bound", "failed", "detach_pending", "detached"
SmartnessLevelsResponseDto
| Property | Type | Required | Description |
|---|
levels | array of string | yes | The selectable "smartness" (modelLane) levels for the current org — model-lane keys. An OPEN vocabulary: the set is whatever this organisation's installed biomes have contributed, so a consumer must not treat it as a closed enum or hardcode its members. The frontend maps each raw key to a friendly label. |
SmartnessLevelsResponseDtoDataEnvelope
SpaceKind
The tier of the Space the binding lives in (set by your organization, project or you).
Type: one of "system", "org", "project", "app", "session", "biome", "user"
SpaceRefResponseDto
| Property | Type | Required | Description |
|---|
appId | string | no | |
biomeId | string | no | |
orgId | string | no | |
projectId | string | no | |
sessionId | string | no | |
tier | one of "system", "org", "project", "app", "session", "biome", "user" | yes | |
userId | string | no | |
StartBuildImageDto
| Property | Type | Required | Description |
|---|
buildArgs | array of string | no | Optional --build-arg values to inject into the build. Pass as KEY=value entries. |
dockerfilePath | string | no | Dockerfile path inside the workspace, relative to the primary repo root. Defaults to Dockerfile. |
SubjectRefResponseDto
| Property | Type | Required | Description |
|---|
id | string | yes | |
kind | string (12 values) | yes | |
TerminalAction
Every right the caller holds that applies to this screen.
Type: one of "view", "control", "admin-view"
TerminalAttachAvailabilityDto
| Property | Type | Required | Description |
|---|
available | boolean | yes | Whether an attach to this screen would be admitted right now. |
refusal | TerminalAttachRefusalCode | no | Why an attach would be refused. Absent when available is true. |
TerminalAttachRefusalCode
Why an attach would be refused. Absent when available is true.
Type: string (9 values)
TerminalDescribeResponseDto
| Property | Type | Required | Description |
|---|
screens | array of TerminalScreenDto | yes | The screens the caller may see. The owner-only screen is present only for the session owner. |
TerminalDescribeResponseDtoDataEnvelope
TerminalScreenDto
TerminalScreenParam
Type: one of "shared", "owner-only"
TextDeltaPayloadDto
| Property | Type | Required | Description |
|---|
text | string | yes | Incremental text fragment from the assistant message stream. |
ThreadResponseDto
| Property | Type | Required | Description |
|---|
agentSlug | string or null | no | Per-thread primary agent override. Null = inherit Session.agentSlug. |
createdAt | string (date-time) | yes | |
id | string | yes | Thread identifier (cuid) |
lastActivityAt | string (date-time) | yes | Last time a message was sent or received on this thread. |
modelSelection | object or null | no | Per-thread model override. Same ModelRef-shaped JSON as Session.modelSelection. Null = inherit the Session selection. |
parentThreadId | string or null | no | Parent Thread when this lane was created through the branch API. |
sessionId | string | yes | Session this thread belongs to |
status | ThreadStatus | yes | |
title | string | yes | Human-readable thread title |
turnState | TurnState | yes | Per-thread turn lock state. The agent is busy on this thread iff turnState != idle. |
updatedAt | string (date-time) | yes | |
ThreadResponseDtoDataArrayEnvelope
ThreadResponseDtoDataEnvelope
ThreadStatus
Type: one of "active", "archived"
| Property | Type | Required | Description |
|---|
errorMessage | string | no | Error message when the tool invocation failed. Absent on success. |
status | one of "started", "completed" | yes | Lifecycle status. started is appended on first observation; completed is appended on tool_result. |
toolCallId | string | no | Stable id correlating started + completed rows for the same tool invocation. |
toolName | string | yes | Canonical tool name as reported by the MCP / OpenCode runtime. |
| Property | Type | Required | Description |
|---|
correlation | object | yes | The correlation to echo (kernel HookRequestCorrelation). |
hookPointId | string | yes | |
mode | HookMode | yes | |
operation | string | yes | |
parameters | object | yes | The binding's rules. Each rule can only deny: the first whose match.subject matches the runtime-neutral tool subject and whose every args condition holds denies with its reason. |
phase | HookPhase | yes | |
projection | object | yes | Approved projection: field pointer to value (/subject, /args). |
synchronousChain | array of string | yes | |
writableFields | array of string | yes | |
| Property | Type | Required | Description |
|---|
correlation | object | yes | |
verdict | object | yes | Kernel HookVerdict: allow, or deny with the rule reason. |
| Property | Type | Required | Description |
|---|
bindingId | string | yes | Id of the binding that refused the call. |
reason | ToolDenialReasonDto | yes | |
| Property | Type | Required | Description |
|---|
bindingId | string | yes | Id of the binding whose evaluation failed. |
code | HookFailureCode | yes | The kernel failure code of that binding. |
| Property | Type | Required | Description |
|---|
code | string | yes | Stable machine code of the refusal. |
message | string | no | The binding handler's own words. |
ToolUsageEntryDto
| Property | Type | Required | Description |
|---|
command | string | yes | Canonical tool name (the name field of the MCP tools/call envelope). |
count | number | yes | Number of successful tools/call invocations recorded for this (slug, command) within the 30-day TTL window. |
mcpServiceSlug | string | yes | MCP service slug — ${providerKind}:${resourceId} of the relayed call. |
| Property | Type | Required | Description |
|---|
entries | array of ToolUsageEntryDto | yes | Per-(slug, command) counters sorted by count descending. |
warning | ToolUsageWarning | no | Set when the counters could not be read from their owning service. entries is empty in that case and does NOT mean "no tools were used". The relay path is unaffected — counters keep incrementing. |
Set when the counters could not be read from their owning service. entries is empty in that case and does NOT mean "no tools were used". The relay path is unaffected — counters keep incrementing.
Type: one of "TELEMETRY_UNAVAILABLE"
TurnState
Per-thread turn lock state. The agent is busy on this thread iff turnState != idle.
Type: one of "idle", "executing", "interrupting"
UpdateThreadDto
| Property | Type | Required | Description |
|---|
status | ThreadStatus | no | New thread lifecycle status (e.g. archived). |
title | string | no | New thread title. |
UsageResponseDto
| Property | Type | Required | Description |
|---|
budgetLimit | object or null | no | null if no budget set |
budgetRatio | object or null | no | Ratio of total tokens to budget limit (null if no budget) |
inputTokens | number | yes | |
outputTokens | number | yes | |
totalTokens | number | yes | |
UsageResponseDtoDataEnvelope
WorkerInternetEgress
Optional narrowing of whether this session's workspace pod may open sockets to the public internet. Tighten-only and pinned for the session's life. Absent states nothing.
Type: one of "open", "governed"
WorkingFileObjectDto
| Property | Type | Required | Description |
|---|
key | string | yes | The bound object's authorization type (for example <biome>_<type>). |
ref | string | yes | The bound object's id within the organization. |
WorkingFileUserEditDto
| Property | Type | Required | Description |
|---|
content | string | yes | The user's new base content (their editor buffer). Empty string is valid: the file may be cleared. |
WorkspaceBackingDto
| Property | Type | Required | Description |
|---|
kind | WorkspaceBackingKind | yes | |
storageRef | string | no | Opaque storage allocation reference. Required only for durable-storage backing. |
WorkspaceBackingKind
Type: one of "none", "durable-storage"
WorkspaceResponseDto
| Property | Type | Required | Description |
|---|
backing | WorkspaceBackingDto | yes | |
contentGeneration | string | yes | Monotonic committed workspace content generation. |
createdAt | string | yes | |
createdBy | object | yes | |
displayName | string | yes | |
id | string | yes | |
leaseEpoch | string | yes | Monotonic write-lease fencing epoch. |
orgId | string | yes | |
ownerSpaceRef | object | yes | |
slug | string | yes | |
status | WorkspaceStatus | yes | |
updatedAt | string | yes | |
WorkspaceResponseDtoDataEnvelope
WorkspaceResponseDtoPaginatedEnvelope
WorkspaceStatus
Type: one of "active", "archived"