AgentKit Studio
Concepts

Sessions and workspaces

A session is a DSH-owned event journal; a workspace is the directory that bounds what it may write.

A session is a durable event journal owned by DSH; a workspace is the directory that session is bound to. The first answers where history lives, the second answers what the agent may write.

These two concepts are often merged into "a session is one conversation", yet their lifecycle, ownership, and failure modes differ. This page takes them separately and then shows where they meet on a single run.

Why they must stay separate

QuestionGoverned by sessionGoverned by workspace
Does history survive a page refresh?✅ The journal is persisted by the Host—
Which files may the agent change?—✅ The directory boundary sets the write scope
Do two sessions of one agent contaminate each other?❌ Independent event sequences❌ They may point at different directories
Can work continue on another machine?Depends on the persistence backendDepends on whether the directory travels

Conflating them produces one classic mistake: assuming a new session means a new working directory. A new session opens a new event sequence; the directory is fixed by the workspace binding.

Session: the journal belongs to DSH

Studio does not own the transcript. It does four things only: validate identity, project one proven message shape, preserve unsupported facts as ignorable events, and serve paginated windows.

Ownership boundary

The durable journal, node assembler, remote channel, and renderer all belong to DSH. Studio's session adapter is a narrow boundary, not a second store.

The 16 event types

CategoryEvents
Turnturn/start, turn/end
Stepstep/start, step/end
Messagessystem/message, user/message, assistant/message, assistant/attempt
Toolstool/call, tool/result
Approvalapproval/asked, approval/decided
Requestsrequest/header, request/context
Orchestrationagent/inbox/spliced, agent-preset/selected

Besides events there are 3 in-process stream frames: start, chunk, end. Frames are deltas, not events, and never enter the durable journal.

The canonical event envelope

Every event must carry all of these fields; missing one keeps it out of the projection:

FieldConstraint
event_idNon-empty string
event_typeNon-empty string
run_idNon-empty string
scope_idNon-empty string
seqNon-negative safe integer
timestampNon-negative finite number
schema_versionMust equal 2

Conflicts are rejected rather than overwritten: the same event_id twice with different content raises "event changed during replay"; two different event_ids claiming one seq also raise. A byte-identical duplicate is idempotent and skipped.

Official versus ignorable types

11 events are "official" and render as normal chat nodes. Every other type is prefixed with ksadk/ and marked ignorable — facts the Host does not understand are preserved without breaking the conversation UI. That rule lets new events land before the renderer knows them.

There is also a dedicated guard: events that arrive after their run has ended (history paging and reconnect tails arrive out of order) are demoted to ignorable types. Otherwise a late event would be projected into the chat and read as the model speaking after it finished.

Transient frames: client-only, never journaled

Unfinished assistant messages need live deltas. They are expressed as assistant/live-chunk frames carrying a fractional sequence number (seq + 0.5), meaning "sits between two durable events".

TraitDurable eventTransient frame
Enters the journal✅❌ Never
Appears in snapshot responses✅Only in the client window
Sequence numberIntegerFractional (n + 0.5)
PurposeSource of truthTypewriter effect

The line is hard: journaling a transient frame would replay duplicated text after a reconnect.

Session identity and versions

ItemValue
Session contractp1-session-contract-v0.1
History contract version2
Persistence backenddsh-native-disk
Shared across podsNo
Active run restorableNo (history is readable; an unfinished turn does not resume automatically)
Invalid session IDRUNTIME_SESSION_ID_INVALID
Session ID conflictRUNTIME_SESSION_ID_CONFLICT

Session ownership belongs to agent state, not deployment-version state. Updating a deployment version therefore never makes existing sessions disappear — the session directory sits outside the version directory.

Workspace: a directory boundary

A workspace is simply the current directory a session is bound to. It defaults to the Host process's working directory and can be overridden by an environment variable. It is not an abstraction; it is a real path boundary:

ScenarioBehavior
DefaultThe Host process working directory
Set by environment variableResolved to an absolute path, which becomes the boundary
A local Star Harness session with no workspace routeNATIVE_ENGINE_WORKSPACE_UNAVAILABLE, asking you to pick a configured workspace
Execution policy read-onlyAll writes refused
Execution policy workspace-writeWrites inside the workspace allowed
Execution policy danger-full-accessWrites outside the workspace allowed

The workspace also carries a state-root isolation rule: the roots for command state, A2A state, browser state, and so on may be neither the workspace itself, nor inside it, nor a parent of it. State is sharded by agent, workspace digest, and session, so two sessions of two agents never share read-before-edit state.

Where the two concepts meet

A single run needs both sides:

ParticipantProvidesIf missing
SessionsessionId, event sequence, history pagingThe run cannot be located
WorkspaceCurrent directory, write boundaryTools cannot execute
RevisionagentId, revisionNo definition to run
BuildbuildIdNo reproducibility

All four sources are required for a legal run — see Agent · Revision · Build · Run.

Hard rules

  1. Studio never writes the session journal. It projects DSH events; writing the journal is DSH's job.
  2. Transient frames never enter the journal. Fractional sequence numbers exist for client ordering only.
  3. schema_version must equal 2. Other versions are rejected instead of inferred.
  4. Non-official event types must be ignorable. Unknown facts are preserved without breaking the UI.
  5. A workspace is a path boundary, not a namespace. Changing the directory changes the boundary.
  6. State roots and the workspace must not contain each other, or read-before-edit state pollutes the workspace.
What you needWhich page
Fields of the 16 events and 3 stream framesSession events
RUNTIME_* and SESSION_* error codesErrors
The 24 sessions/* operationsOperations
Workspace and execution-policy environment variablesEnvironment

On this page