Session

The session object every lifecycle method returns or lists.

Additive-optional evolution applies: clients must ignore unknown fields.

Fields and variants

• activeTurnId
• approvalMode
• createdAt
• forkedFrom
• modelId
• path
• providerId
• sessionId
• status
• turnCount
• updatedAt
• workspaceRoot

Source

schema/msp/experimental/msp.schema.json#/types/Session

{
  "description": "The session object every lifecycle method returns or lists.\n\nAdditive-optional evolution applies: clients must ignore unknown fields.",
  "properties": {
    "activeTurnId": {
      "description": "The `turnId` of the current foreground turn when `status` is\n`running`, and `null` when the session is idle.\n\n**Required-nullable, per the owner ruling**. Both\nproduction writers hard-code `\"activeTurnId\": null` and nothing\nstrips it, so this is what the binary emits and what the protocol's example\nspells. The optional-absent shape published it as plain `string` and\nREJECTED every idle `Session` frame the host sent — the defect\nclass this PR exists to close.\n\nThe ruling's original evidence for optional-absent (\"every committed\ntranscript shows the omission\") was wrong: those transcripts are\nhand-authored fixtures, not host recordings. They are corrected in the\nsame change under the ruling's `regenerationJustification`.",
      "type": [
        "string",
        "null"
      ]
    },
    "approvalMode": {
      "$ref": "#/$defs/EffectiveApprovalModeState",
      "description": "The folded effective approval mode. **Additive-optional**: a Session\nobject that omits it means the host has not folded a mode, which is\nwhy the index-derived `session/list` entry may legitimately omit it."
    },
    "createdAt": {
      "description": "RFC3339. For a fork this is the fork session id's UUIDv7 mint instant.",
      "type": "string"
    },
    "forkedFrom": {
      "anyOf": [
        {
          "$ref": "#/$defs/ForkProvenance"
        },
        {
          "type": "null"
        }
      ],
      "description": "`null` for root sessions; fork provenance otherwise."
    },
    "modelId": {
      "description": "The winning metadata fold's model; `null` when that record omits it.",
      "type": [
        "string",
        "null"
      ]
    },
    "path": {
      "description": "Absolute path of the session's durable log; non-nullable. Under the\nephemeral session profile it is the **empty string**, meaning \"no\ndurable log exists\" — the one value a client must not\nhand to a filesystem call.",
      "type": "string"
    },
    "providerId": {
      "description": "The winning metadata fold's provider; `null` when that record omits it.",
      "type": [
        "string",
        "null"
      ]
    },
    "sessionId": {
      "description": "The session identity.",
      "type": "string"
    },
    "status": {
      "$ref": "#/$defs/SessionStatus",
      "description": "Load state as this host knows it; `session/list` reports `notLoaded`\nfor sessions loaded by *other* hosts."
    },
    "turnCount": {
      "description": "Completed-turn count from the session view fold.",
      "type": "integer"
    },
    "updatedAt": {
      "description": "RFC3339; never precedes `createdAt`.",
      "type": "string"
    },
    "workspaceRoot": {
      "description": "The winning metadata fold's workspace root; `null` when that record\nomits it — absent is never fabricated.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "activeTurnId",
    "createdAt",
    "forkedFrom",
    "modelId",
    "path",
    "providerId",
    "sessionId",
    "status",
    "turnCount",
    "updatedAt",
    "workspaceRoot"
  ],
  "type": "object"
}