@ellipsis-dev/sdk 0.1.0

package/schema/frames.schema.json

@@ -0,0 +1,1427 @@
+{
+  "$defs": {
+    "AgentSessionExitStatus": {
+      "description": "Why a terminal agent session ended \u2014 a finer-grained reason than `status`.\n\n`status` (AgentSessionStatus) is the lifecycle state: COMPLETED / ERROR /\nCANCELLED. `exit_status` explains *why* a run reached that terminal state, so\nthe UI and metrics can tell a budget cutoff apart from a crashed tool call or\na deliberate cancellation. It is None until the run reaches a terminal state.",
+      "enum": [
+        "completed",
+        "budget_hit",
+        "payment_required",
+        "tool_call_failed",
+        "lifecycle_hook_failed",
+        "missing_repo_access",
+        "missing_token_permissions",
+        "cancelled",
+        "interrupted",
+        "error",
+        "stopped"
+      ],
+      "title": "AgentSessionExitStatus",
+      "type": "string"
+    },
+    "AgentSessionPr": {
+      "description": "A pull request this session created, denormalized at capture time so\nsession surfaces render a labeled link without joining gh_prs. Live PR\nstate (open/merged/closed) is not stored here \u2014 read it from gh_prs where\na view needs it.",
+      "properties": {
+        "gh_pr_id": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Gh Pr Id"
+        },
+        "number": {
+          "title": "Number",
+          "type": "integer"
+        },
+        "repo_full_name": {
+          "title": "Repo Full Name",
+          "type": "string"
+        },
+        "title": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Title"
+        },
+        "url": {
+          "title": "Url",
+          "type": "string"
+        }
+      },
+      "required": [
+        "gh_pr_id",
+        "number",
+        "repo_full_name",
+        "title",
+        "url"
+      ],
+      "title": "AgentSessionPr",
+      "type": "object"
+    },
+    "AgentSessionSource": {
+      "enum": [
+        "react",
+        "manual",
+        "api",
+        "cli",
+        "mention",
+        "cron",
+        "laptop"
+      ],
+      "title": "AgentSessionSource",
+      "type": "string"
+    },
+    "AgentSessionStatus": {
+      "enum": [
+        "scheduled",
+        "creating_sandbox",
+        "running",
+        "retrying",
+        "completed",
+        "error",
+        "cancelled",
+        "stopped"
+      ],
+      "title": "AgentSessionStatus",
+      "type": "string"
+    },
+    "AgentSessionWire": {
+      "properties": {
+        "agent_config_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Agent Config Id"
+        },
+        "attributed_user": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/GithubAccountSnippet"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "attribution_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Attribution Id"
+        },
+        "attribution_type": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/AttributionType"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "client_version": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Client Version"
+        },
+        "config_override": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Config Override"
+        },
+        "context_repository": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Context Repository"
+        },
+        "cost_fee": {
+          "default": 0,
+          "title": "Cost Fee",
+          "type": "integer"
+        },
+        "cost_sandbox_cpu": {
+          "default": 0,
+          "title": "Cost Sandbox Cpu",
+          "type": "integer"
+        },
+        "cost_sandbox_memory": {
+          "default": 0,
+          "title": "Cost Sandbox Memory",
+          "type": "integer"
+        },
+        "cost_tokens": {
+          "title": "Cost Tokens",
+          "type": "integer"
+        },
+        "created_at": {
+          "format": "date-time",
+          "title": "Created At",
+          "type": "string"
+        },
+        "customer_id": {
+          "title": "Customer Id",
+          "type": "string"
+        },
+        "default_resolution": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/DefaultResolution"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "exit_status": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/AgentSessionExitStatus"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "harness": {
+          "$ref": "#/$defs/Harness"
+        },
+        "id": {
+          "title": "Id",
+          "type": "string"
+        },
+        "last_activity_at": {
+          "anyOf": [
+            {
+              "format": "date-time",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Last Activity At"
+        },
+        "last_message_at": {
+          "anyOf": [
+            {
+              "format": "date-time",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Last Message At"
+        },
+        "live_summary": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Live Summary"
+        },
+        "metadata": {
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {},
+          "title": "Metadata",
+          "type": "object"
+        },
+        "output_prs": {
+          "anyOf": [
+            {
+              "items": {
+                "$ref": "#/$defs/AgentSessionPr"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Output Prs"
+        },
+        "parent_agent_session_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Parent Agent Session Id"
+        },
+        "parent_kind": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ParentKind"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "prompt": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Prompt"
+        },
+        "replayed_from_session_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Replayed From Session Id"
+        },
+        "resolved_budget_cents": {
+          "title": "Resolved Budget Cents",
+          "type": "integer"
+        },
+        "resolved_budget_source": {
+          "$ref": "#/$defs/BudgetSource"
+        },
+        "sandbox_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Sandbox Id"
+        },
+        "session_key": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Session Key"
+        },
+        "session_state": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SessionState"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "source": {
+          "$ref": "#/$defs/AgentSessionSource"
+        },
+        "status": {
+          "$ref": "#/$defs/AgentSessionStatus"
+        },
+        "status_reason": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Status Reason"
+        },
+        "stopped_at": {
+          "anyOf": [
+            {
+              "format": "date-time",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Stopped At"
+        },
+        "stopped_by": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Stopped By"
+        },
+        "stopped_by_user": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/GithubAccountSnippet"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "surface": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SessionSurface"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "tokens_cache_creation": {
+          "default": 0,
+          "title": "Tokens Cache Creation",
+          "type": "integer"
+        },
+        "tokens_cache_read": {
+          "default": 0,
+          "title": "Tokens Cache Read",
+          "type": "integer"
+        },
+        "tokens_input": {
+          "default": 0,
+          "title": "Tokens Input",
+          "type": "integer"
+        },
+        "tokens_model": {
+          "title": "Tokens Model",
+          "type": "string"
+        },
+        "tokens_output": {
+          "default": 0,
+          "title": "Tokens Output",
+          "type": "integer"
+        },
+        "tokens_total": {
+          "default": 0,
+          "title": "Tokens Total",
+          "type": "integer"
+        },
+        "updated_at": {
+          "format": "date-time",
+          "title": "Updated At",
+          "type": "string"
+        },
+        "webhook_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Webhook Id"
+        },
+        "webhook_type": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/WebhookType"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        }
+      },
+      "required": [
+        "agent_config_id",
+        "attributed_user",
+        "attribution_id",
+        "attribution_type",
+        "client_version",
+        "config_override",
+        "context_repository",
+        "cost_fee",
+        "cost_sandbox_cpu",
+        "cost_sandbox_memory",
+        "cost_tokens",
+        "created_at",
+        "customer_id",
+        "default_resolution",
+        "exit_status",
+        "harness",
+        "id",
+        "last_activity_at",
+        "last_message_at",
+        "live_summary",
+        "metadata",
+        "output_prs",
+        "parent_agent_session_id",
+        "parent_kind",
+        "prompt",
+        "replayed_from_session_id",
+        "resolved_budget_cents",
+        "resolved_budget_source",
+        "sandbox_id",
+        "session_key",
+        "session_state",
+        "source",
+        "status",
+        "status_reason",
+        "stopped_at",
+        "stopped_by",
+        "stopped_by_user",
+        "surface",
+        "tokens_cache_creation",
+        "tokens_cache_read",
+        "tokens_input",
+        "tokens_model",
+        "tokens_output",
+        "tokens_total",
+        "updated_at",
+        "webhook_id",
+        "webhook_type"
+      ],
+      "title": "AgentSessionWire",
+      "type": "object"
+    },
+    "AttributionType": {
+      "enum": [
+        "github_user",
+        "linear_user",
+        "slack_user",
+        "api_key"
+      ],
+      "title": "AttributionType",
+      "type": "string"
+    },
+    "BudgetSource": {
+      "description": "Which layer actually determined the enforced budget.\n\nNot derivable from the run row alone (the run does not store the config\ncents or the customer default), so we persist it for the UI / audit.",
+      "enum": [
+        "system",
+        "account",
+        "config",
+        "run"
+      ],
+      "title": "BudgetSource",
+      "type": "string"
+    },
+    "DefaultResolution": {
+      "description": "How a session that arrived with no explicit config source resolved its\nconfig (documents/eng/DEFAULT_CONFIGS.md \u00a74). Persisted on the session so\naudit and clients can say \"ran under X (repo default)\". A session started\nwith an explicit config/config_id/template_id never enters resolution and\nstores None.",
+      "enum": [
+        "repo_default",
+        "account_default",
+        "none"
+      ],
+      "title": "DefaultResolution",
+      "type": "string"
+    },
+    "DeltaFrame": {
+      "description": "Fire-and-forget partial assistant output for the current response.\nNo seq, never resumable; superseded by the committed record.",
+      "properties": {
+        "agent_turn_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Agent Turn Id"
+        },
+        "kind": {
+          "description": "What the partial text is. Known values: text ('thinking' reserved). Open vocabulary: ignore deltas with unknown kinds.",
+          "type": "string"
+        },
+        "output_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Output Tokens"
+        },
+        "text": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Text"
+        },
+        "type": {
+          "const": "delta",
+          "default": "delta",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "agent_turn_id",
+        "kind",
+        "output_tokens",
+        "text",
+        "type"
+      ],
+      "title": "DeltaFrame",
+      "type": "object"
+    },
+    "DoneFrame": {
+      "description": "Terminal marker: the conversation is over, after the final session frame\ncarried the end state. Followed by close 1000.",
+      "properties": {
+        "type": {
+          "const": "done",
+          "default": "done",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "title": "DoneFrame",
+      "type": "object"
+    },
+    "ErrorFrame": {
+      "description": "Terminal error marker, before close 1011. Curated copy only.",
+      "properties": {
+        "message": {
+          "title": "Message",
+          "type": "string"
+        },
+        "type": {
+          "const": "error",
+          "default": "error",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "message",
+        "type"
+      ],
+      "title": "ErrorFrame",
+      "type": "object"
+    },
+    "GithubAccountSnippet": {
+      "description": "Sometimes the GitHub API returns a user of github (can include bots)\nusing this snippet instead of the full GithubAccount model. One example,\nis when the API returns a pull request.\n\nThis is the least amount of info we need to represent a GitHub account.",
+      "properties": {
+        "avatar_url": {
+          "title": "Avatar Url",
+          "type": "string"
+        },
+        "id": {
+          "title": "Id",
+          "type": "integer"
+        },
+        "login": {
+          "title": "Login",
+          "type": "string"
+        },
+        "type": {
+          "$ref": "#/$defs/GithubAccountType"
+        }
+      },
+      "required": [
+        "avatar_url",
+        "id",
+        "login",
+        "type"
+      ],
+      "title": "GithubAccountSnippet",
+      "type": "object"
+    },
+    "GithubAccountType": {
+      "enum": [
+        "User",
+        "Organization",
+        "Bot",
+        "Mannequin"
+      ],
+      "title": "GithubAccountType",
+      "type": "string"
+    },
+    "Harness": {
+      "enum": [
+        "claude_code"
+      ],
+      "title": "Harness",
+      "type": "string"
+    },
+    "HeartbeatFrame": {
+      "description": "Sent after HEARTBEAT_SECONDS of idleness; doubles as the dead-socket\nprobe.",
+      "properties": {
+        "ts": {
+          "format": "date-time",
+          "title": "Ts",
+          "type": "string"
+        },
+        "type": {
+          "const": "heartbeat",
+          "default": "heartbeat",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "ts",
+        "type"
+      ],
+      "title": "HeartbeatFrame",
+      "type": "object"
+    },
+    "MessagesFrame": {
+      "description": "LWW snapshot of the OPEN inbox slice: all PENDING rows plus rows that\nflipped (delivered, re-pended) within this connection since the last frame.\nDeliberately not the full message history \u2014 delivered rows render through\ntheir transcript user-echo records; structural history stays on REST\n/turns (\u00a73.3).",
+      "properties": {
+        "messages": {
+          "items": {
+            "$ref": "#/$defs/SessionMessageWire"
+          },
+          "title": "Messages",
+          "type": "array"
+        },
+        "type": {
+          "const": "messages",
+          "default": "messages",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "messages",
+        "type"
+      ],
+      "title": "MessagesFrame",
+      "type": "object"
+    },
+    "ModelTokensInfo": {
+      "properties": {
+        "cache_creation_input_tokens": {
+          "default": 0,
+          "title": "Cache Creation Input Tokens",
+          "type": "integer"
+        },
+        "cache_read_input_tokens": {
+          "default": 0,
+          "title": "Cache Read Input Tokens",
+          "type": "integer"
+        },
+        "cost_usd": {
+          "default": 0,
+          "title": "Cost Usd",
+          "type": "number"
+        },
+        "input_tokens": {
+          "default": 0,
+          "title": "Input Tokens",
+          "type": "integer"
+        },
+        "output_tokens": {
+          "default": 0,
+          "title": "Output Tokens",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "cache_creation_input_tokens",
+        "cache_read_input_tokens",
+        "cost_usd",
+        "input_tokens",
+        "output_tokens"
+      ],
+      "title": "ModelTokensInfo",
+      "type": "object"
+    },
+    "ParentKind": {
+      "description": "How a session relates to its predecessor (parent_agent_session_id) \u2014\nthe ONE \"preceded-by\" chain for every predecessor relationship. Routing\nreads this when the distinction matters.\n\nCONTINUATION \u2014 a follow-up in the same conversation surface (e.g. a Slack\nthread reply spawning a fresh session on the same thread).\nHANDOFF \u2014 a session started to take over work from another surface (e.g.\nlaptop \u2192 cloud handoff; later phase).\nRESUME \u2014 a conversation re-hosted on a new box after its sandbox was torn\ndown (interactive platform; later phase).",
+      "enum": [
+        "continuation",
+        "handoff",
+        "resume"
+      ],
+      "title": "ParentKind",
+      "type": "string"
+    },
+    "RecordsAppendFrame": {
+      "description": "Cursored append-only: raw records ordered by feed_seq, all sources.\nEvery record in the frame advances the resume cursor \u2014 including ones a\nclient renders as nothing (\u00a73.4).",
+      "properties": {
+        "records": {
+          "items": {
+            "$ref": "#/$defs/SessionRecordWire"
+          },
+          "title": "Records",
+          "type": "array"
+        },
+        "type": {
+          "const": "records_append",
+          "default": "records_append",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "records",
+        "type"
+      ],
+      "title": "RecordsAppendFrame",
+      "type": "object"
+    },
+    "RunStatus": {
+      "description": "What the current (or most recent) execution is doing (backs `run`).",
+      "enum": [
+        "scheduled",
+        "starting",
+        "working",
+        "waiting",
+        "done",
+        "failed",
+        "stopped",
+        "cancelled",
+        "retrying"
+      ],
+      "title": "RunStatus",
+      "type": "string"
+    },
+    "SessionFrame": {
+      "description": "LWW snapshot of the enriched public session (\u00a74.1) \u2014 the only way\nstatus/state/cost arrive. Resent whole on any field change.",
+      "properties": {
+        "session": {
+          "$ref": "#/$defs/AgentSessionWire"
+        },
+        "type": {
+          "const": "session",
+          "default": "session",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "session",
+        "type"
+      ],
+      "title": "SessionFrame",
+      "type": "object"
+    },
+    "SessionLiveness": {
+      "description": "The durable conversation axis (backs the surfaced `session` field).",
+      "enum": [
+        "alive",
+        "sleeping",
+        "closed"
+      ],
+      "title": "SessionLiveness",
+      "type": "string"
+    },
+    "SessionMessageStatus": {
+      "enum": [
+        "pending",
+        "delivered"
+      ],
+      "title": "SessionMessageStatus",
+      "type": "string"
+    },
+    "SessionMessageWire": {
+      "description": "The wire shape of one inbox message (\u00a73.3): what a queued chip renders\nand retires on. `author` is the message's attribution string; the webhook\nprovenance internals stay off the wire.",
+      "properties": {
+        "agent_session_id": {
+          "title": "Agent Session Id",
+          "type": "string"
+        },
+        "author": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Author"
+        },
+        "body": {
+          "title": "Body",
+          "type": "string"
+        },
+        "created_at": {
+          "format": "date-time",
+          "title": "Created At",
+          "type": "string"
+        },
+        "delivered_at": {
+          "anyOf": [
+            {
+              "format": "date-time",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Delivered At"
+        },
+        "delivered_turn_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Delivered Turn Id"
+        },
+        "feed_seq": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Feed Seq"
+        },
+        "id": {
+          "title": "Id",
+          "type": "string"
+        },
+        "sender_attribution_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Sender Attribution Id"
+        },
+        "sender_attribution_type": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/AttributionType"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "status": {
+          "$ref": "#/$defs/SessionMessageStatus"
+        }
+      },
+      "required": [
+        "agent_session_id",
+        "author",
+        "body",
+        "created_at",
+        "delivered_at",
+        "delivered_turn_id",
+        "feed_seq",
+        "id",
+        "sender_attribution_id",
+        "sender_attribution_type",
+        "status"
+      ],
+      "title": "SessionMessageWire",
+      "type": "object"
+    },
+    "SessionRecordWire": {
+      "description": "The wire shape of one session record (\u00a73.3): the \u00a73.6 stable envelope +\nthe native `payload`, by explicit allowlist. Internal-only columns\n(`search_text`, `clis`, ingest bookkeeping, attribution denormalizations)\nare deliberately absent so internal model evolution stays free.",
+      "properties": {
+        "agent_session_id": {
+          "title": "Agent Session Id",
+          "type": "string"
+        },
+        "agent_turn_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Agent Turn Id"
+        },
+        "cost": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Cost"
+        },
+        "created_at": {
+          "format": "date-time",
+          "title": "Created At",
+          "type": "string"
+        },
+        "duration": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Duration"
+        },
+        "feed_seq": {
+          "title": "Feed Seq",
+          "type": "integer"
+        },
+        "id": {
+          "title": "Id",
+          "type": "string"
+        },
+        "model": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Model"
+        },
+        "payload": {
+          "additionalProperties": true,
+          "title": "Payload",
+          "type": "object"
+        },
+        "record_format": {
+          "title": "Record Format",
+          "type": "string"
+        },
+        "record_type": {
+          "title": "Record Type",
+          "type": "string"
+        },
+        "session_message_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Session Message Id"
+        },
+        "source": {
+          "description": "Who wrote the record. Known values: claude_code (a native harness transcript record) | lifecycle (a platform notification). Open vocabulary: ignore records with unknown sources.",
+          "type": "string"
+        },
+        "stream_seq": {
+          "title": "Stream Seq",
+          "type": "integer"
+        },
+        "tokens_info": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/TokensInfo"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "tools": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Tools"
+        }
+      },
+      "required": [
+        "agent_session_id",
+        "agent_turn_id",
+        "cost",
+        "created_at",
+        "duration",
+        "feed_seq",
+        "id",
+        "model",
+        "payload",
+        "record_format",
+        "record_type",
+        "session_message_id",
+        "source",
+        "stream_seq",
+        "tokens_info",
+        "tools"
+      ],
+      "title": "SessionRecordWire",
+      "type": "object"
+    },
+    "SessionState": {
+      "description": "Lifecycle of a keyed (multi-turn) session \u2014 the durable conversation.\nDistinct from AgentSessionStatus, which is per-execution (one turn's run) and\nmoves to agent_turns in a later slice. IDLE: alive, waiting for the next\nmessage. RUNNING: a turn is executing. CLOSED: the conversation is done and\nits sandbox/snapshots are torn down.",
+      "enum": [
+        "idle",
+        "running",
+        "closed"
+      ],
+      "title": "SessionState",
+      "type": "string"
+    },
+    "SessionSurface": {
+      "description": "The three fields we expose. All `None` for an un-keyed (laptop) session.\n\n`use_enum_values=True` (from CustomBaseModel) stores the members as their\nstring values, so this serializes to `{\"session\": \"alive\", \"run\": \"waiting\",\n\"status\": \"waiting\"}` \u2014 a plain object, not enum names.",
+      "properties": {
+        "run": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/RunStatus"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "session": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SessionLiveness"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "status": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Status"
+        }
+      },
+      "required": [
+        "run",
+        "session",
+        "status"
+      ],
+      "title": "SessionSurface",
+      "type": "object"
+    },
+    "SnapshotFrame": {
+      "description": "First frame after accept. Lean: session + open inbox only \u2014 records\nalways arrive via records_append (\u00a73.4).",
+      "properties": {
+        "earliest_feed_seq": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Earliest Feed Seq"
+        },
+        "messages": {
+          "items": {
+            "$ref": "#/$defs/SessionMessageWire"
+          },
+          "title": "Messages",
+          "type": "array"
+        },
+        "protocol": {
+          "default": 2,
+          "title": "Protocol",
+          "type": "integer"
+        },
+        "session": {
+          "$ref": "#/$defs/AgentSessionWire"
+        },
+        "type": {
+          "const": "snapshot",
+          "default": "snapshot",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "earliest_feed_seq",
+        "messages",
+        "protocol",
+        "session",
+        "type"
+      ],
+      "title": "SnapshotFrame",
+      "type": "object"
+    },
+    "TokensInfo": {
+      "properties": {
+        "cache_creation_input_tokens": {
+          "default": 0,
+          "title": "Cache Creation Input Tokens",
+          "type": "integer"
+        },
+        "cache_read_input_tokens": {
+          "default": 0,
+          "title": "Cache Read Input Tokens",
+          "type": "integer"
+        },
+        "cost_usd": {
+          "default": 0,
+          "title": "Cost Usd",
+          "type": "number"
+        },
+        "initial_system_prompt_tokens": {
+          "default": 0,
+          "title": "Initial System Prompt Tokens",
+          "type": "integer"
+        },
+        "input_tokens": {
+          "default": 0,
+          "title": "Input Tokens",
+          "type": "integer"
+        },
+        "num_turns": {
+          "default": 0,
+          "title": "Num Turns",
+          "type": "integer"
+        },
+        "output_tokens": {
+          "default": 0,
+          "title": "Output Tokens",
+          "type": "integer"
+        },
+        "per_model": {
+          "additionalProperties": {
+            "$ref": "#/$defs/ModelTokensInfo"
+          },
+          "default": {},
+          "title": "Per Model",
+          "type": "object"
+        },
+        "per_turn": {
+          "default": [],
+          "items": {
+            "$ref": "#/$defs/TurnTokensInfo"
+          },
+          "title": "Per Turn",
+          "type": "array"
+        },
+        "thinking_tokens": {
+          "default": 0,
+          "title": "Thinking Tokens",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "cache_creation_input_tokens",
+        "cache_read_input_tokens",
+        "cost_usd",
+        "initial_system_prompt_tokens",
+        "input_tokens",
+        "num_turns",
+        "output_tokens",
+        "per_model",
+        "per_turn",
+        "thinking_tokens"
+      ],
+      "title": "TokensInfo",
+      "type": "object"
+    },
+    "TurnTokensInfo": {
+      "properties": {
+        "cache_creation_input_tokens": {
+          "default": 0,
+          "title": "Cache Creation Input Tokens",
+          "type": "integer"
+        },
+        "cache_read_input_tokens": {
+          "default": 0,
+          "title": "Cache Read Input Tokens",
+          "type": "integer"
+        },
+        "input_tokens": {
+          "default": 0,
+          "title": "Input Tokens",
+          "type": "integer"
+        },
+        "output_tokens": {
+          "default": 0,
+          "title": "Output Tokens",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "cache_creation_input_tokens",
+        "cache_read_input_tokens",
+        "input_tokens",
+        "output_tokens"
+      ],
+      "title": "TurnTokensInfo",
+      "type": "object"
+    },
+    "WebhookType": {
+      "enum": [
+        "github.issue",
+        "github.issue_comment",
+        "github.push",
+        "github.pull_request",
+        "github.pull_request_comment",
+        "github.pull_request_review",
+        "github.pull_request_review_comment",
+        "slack.app_mention",
+        "slack.message",
+        "slack.channel_created",
+        "linear.issue",
+        "linear.issue_comment",
+        "sentry.event_alert",
+        "sentry.metric_alert",
+        "user.message"
+      ],
+      "title": "WebhookType",
+      "type": "string"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "One server-to-client frame of the Ellipsis session stream protocol v2 (WS /v1/sessions/{id}/stream?protocol=2). Clients MUST ignore frames with unknown `type` values \u2014 additive frames are not a protocol break.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/SnapshotFrame"
+    },
+    {
+      "$ref": "#/$defs/RecordsAppendFrame"
+    },
+    {
+      "$ref": "#/$defs/MessagesFrame"
+    },
+    {
+      "$ref": "#/$defs/SessionFrame"
+    },
+    {
+      "$ref": "#/$defs/DeltaFrame"
+    },
+    {
+      "$ref": "#/$defs/HeartbeatFrame"
+    },
+    {
+      "$ref": "#/$defs/DoneFrame"
+    },
+    {
+      "$ref": "#/$defs/ErrorFrame"
+    }
+  ],
+  "title": "SessionStreamFrame"
+}