Session Objects

Session objects are typed, aliased values stored in a session’s context. Any workflow processor or external caller can read and write session objects to share state across executions within the same session.

Envelope

Every session object is stored as an envelope — a JSON document with the following top-level fields:

Field	Type	Description
`revision_id`	string	Revision that owns this object.
`session_id`	string	Session that owns this object.
`alias`	string	Path-style name for this object within the session (see Alias grammar below).
`updated_at`	string	ISO 8601 timestamp of the last `upload_session_object` call.
`value`	object	The typed payload. Must contain at minimum `"type"` as a discriminator.

The value object always begins with a type string that determines the payload shape:

{
  "revision_id": "rev_001",
  "session_id":  "sess_001",
  "alias":       "my_object",
  "updated_at":  "2026-06-06T10:00:00.000000+00:00",
  "value": {
    "type": "...",
    ...
  }
}

Alias grammar (the namespace)

An alias is a path — one or more /-separated segments — so a session’s objects form a filesystem-like namespace (e.g. README.md, missions/a1b2c3/graph, system/config.v2).

Rule	Value
Characters (per segment)	`A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, `-`, `@`
Separator	`/` — one or more segments; no leading/trailing slash, no empty segments
Reserved	a segment may not be `.` or `..`
Length	1–256 characters (whole path)

Uppercase, dots (including leading dots such as .gitignore), and @ are allowed, so aliases can mirror real repository paths. The grammar is enforced when an object is created or overwritten; reads, deletes, and listing accept any alias, so objects predating the grammar remain accessible. This is a session object’s own alias, not to be confused with a session’s or schedule’s alias — the short, stable name used in place of an id, documented in Alias Grammar. The two grammars are deliberately incompatible and never share a value. List Session Objects navigates this namespace with prefix (scope a subtree), delimiter: "/" (browse one level as folders), and cursor pagination.

Managing Session Objects

Operation	Description
Upload Session Object	Create or replace an object (envelope only).
Download Session Object	Read back the full envelope.
List Session Objects	List objects with prefix/delimiter navigation and cursor pagination.

Uploading an object fires a session_object_modified session event. Deleting it fires session_object_deleted.

Types

Some types have additional incremental operations and real-time events beyond the basic upload/download/list.

Type	Description	Details
`message`	A single generative-AI message (role + content + providers + metadata).	See Data Types
`messages`	An ordered sequence of `message` objects representing a conversation log.	See Data Types
`thread`	An append-only stream of structured items. Items live in a separate store with their own API.	See thread
`graph`	A mutable property graph of vertices and edges. Elements live in a separate store with their own API.	See graph

The thread and graph types are envelope-based: uploading the envelope creates the container, and dedicated commands manage the items or elements. Deleting the envelope via delete_session_object cascades and removes all associated items or elements.

Overview

Workflow

Scheduler

ONNX

Session Objects

Envelope

Alias grammar (the namespace)

Managing Session Objects

Types

​Envelope

​Alias grammar (the namespace)

​Managing Session Objects

​Types

Envelope

Alias grammar (the namespace)

Managing Session Objects

Types