Term
WorkSession
A bounded episode of work that coordinates resources and participants. A WorkSession may contain many AgentRuns and ResourceBindings. It is never an MCP connection and never a host chat transcript.
Purpose
Be the unit that binds a ProjectSnapshot, resources, tasks, artifacts, conversations, and agent assignments into one episode with a start and an end.
Relationships
| Name | Target | Kind | Cardinality | Inverse |
|---|---|---|---|---|
project_snapshot | ProjectSnapshot | pins | 0..1 | pinned_by_work_sessions 0..* |
work_profile | WorkProfile | references | 0..1 | work_sessions 0..* |
resource_bindings | ResourceBinding | contains | 0..* | work_session 1 |
agent_runs | AgentRun | contains | 0..* | work_session 1 |
host_conversation_attachments | HostConversation | attaches | 0..* | work_session 0..1 |
tasks | Task | contains | 0..* | work_session 1 |
artifacts | Artifact | contains | 0..* | work_session 0..1 |
participants | Principal | references | 0..* | participating_sessions 0..* |
Lifecycle
Initial proposed. Terminal: closed, aborted.
proposedopenpausedclosedaborted
proposed→openopen→pausedpaused→openopen→closedpaused→closedopen→abortedpaused→abortedproposed→aborted
Invariants
- MUST
pin-exact-snapshot: A project-bound WorkSession MUST pin exactly one ProjectSnapshot revision. - MUST
children-cardinalities: A WorkSession MUST allow 0..* ResourceBindings, AgentRuns, HostConversation attachments, Tasks, and Artifacts. - MUST NOT
not-mcp-connection: A WorkSession MUST NOT be identified with an MCP connection or transport session. - MUST NOT
not-host-conversation: A WorkSession MUST NOT be identified with a HostConversation. - MUST NOT
no-credentials: A portable WorkSession snapshot MUST NOT serialize credentials. - MUST
policy-narrows: WorkSession policy MUST only narrow the pinned project policy.
Aliases
work-episode
Deprecated aliases
session
Not synonyms
- HostConversation: Host chat history may attach to a session; it is not the session.
- AgentRun: An AgentRun is one agent's assignment inside the session.
- Workspace: A workspace is a bound environment, not the coordinating episode.
- MCP session: MCP 2026-07-28 has no protocol-level session; historical transport identifiers are not work episodes.
Examples
- A time-bounded incident response that several agents and a human join.
- A multi-hour implementation episode pinning one ProjectSnapshot.
Anti-examples
- A Crush or Goose chat thread taken as the work itself.
- An MCP transport connection or a historical Mcp-Session-Id.
- A durable Project.
Fields
The identity field is the index of the handle. fields is the exchange shape.
| Name | Kind | Type | Portable | Notes |
|---|---|---|---|---|
work_session_id | identity | name | True | |
project_snapshot_id | reference | name | True | |
work_profile_id | reference | name | True | |
display_name | descriptive | string | True | |
policy | policy | PolicyDocument | True | Must only narrow the pinned ProjectSnapshot policy. |
Native mapping hooks
| System | Native term | Fidelity | Notes |
|---|---|---|---|
project-interop | _none_ | tbd |