@ellipsis-dev/sdk 0.8.1 → 0.10.0

package/schema/frames.schema.json

@@ -1,101 +1,5 @@
 {
   "$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",
-        "missing_sandbox_variables",
-        "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"
-    },
     "AttributionType": {
       "enum": [
         "github_user",
@@ -364,42 +268,13 @@
     "Session": {
       "description": "An agent session: one conversation with an agent, from trigger to\nterminal state. Returned by `GET /sessions/{id}` and carried by the\nsession stream's `session`/`snapshot` frames \u2014 REST and stream never\ndisagree about what a session looks like.",
       "properties": {
-        "attributed_user": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/GithubAccountSnippet"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "The GitHub user the session is attributed to, when the attribution is a GitHub user."
+        "attribution": {
+          "$ref": "#/$defs/SessionAttribution",
+          "description": "The principal this session is attributed to."
         },
-        "attribution_id": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Identifier of the principal the session is attributed to.",
-          "title": "Attribution Id"
-        },
-        "attribution_type": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/AttributionType"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Kind of principal the session is attributed to (e.g. a GitHub user or an API key)."
+        "budget": {
+          "$ref": "#/$defs/SessionBudget",
+          "description": "The spend budget enforced for this session."
         },
         "client_version": {
           "anyOf": [
@@ -454,28 +329,9 @@
           "description": "The \"owner/name\" repository context the session was started in, if any.",
           "title": "Context Repository"
         },
-        "cost_fee": {
-          "default": 0,
-          "description": "Platform fee in millicents.",
-          "title": "Cost Fee",
-          "type": "integer"
-        },
-        "cost_sandbox_cpu": {
-          "default": 0,
-          "description": "Sandbox CPU spend in millicents.",
-          "title": "Cost Sandbox Cpu",
-          "type": "integer"
-        },
-        "cost_sandbox_memory": {
-          "default": 0,
-          "description": "Sandbox memory spend in millicents.",
-          "title": "Cost Sandbox Memory",
-          "type": "integer"
-        },
-        "cost_tokens": {
-          "description": "Token spend in millicents. The session's grand total cost is the sum of cost_tokens, cost_sandbox_cpu, cost_sandbox_memory, and cost_fee.",
-          "title": "Cost Tokens",
-          "type": "integer"
+        "cost": {
+          "$ref": "#/$defs/SessionCost",
+          "description": "What the session cost, in millicents, broken down by leg and carrying its own total."
         },
         "created_at": {
           "description": "When the session was created.",
@@ -498,7 +354,7 @@
         "exit_status": {
           "anyOf": [
             {
-              "$ref": "#/$defs/AgentSessionExitStatus"
+              "$ref": "#/$defs/SessionExitStatus"
             },
             {
               "type": "null"
@@ -570,7 +426,7 @@
           "anyOf": [
             {
               "items": {
-                "$ref": "#/$defs/AgentSessionPr"
+                "$ref": "#/$defs/SessionPr"
               },
               "type": "array"
             },
@@ -582,30 +438,9 @@
           "description": "Pull requests the session created or updated.",
           "title": "Output Prs"
         },
-        "parent_kind": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/ParentKind"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "How this session relates to its parent session, if any."
-        },
-        "parent_session_id": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Identifier of the parent session that spawned this one, if any.",
-          "title": "Parent Session Id"
+        "parent": {
+          "$ref": "#/$defs/SessionParent",
+          "description": "What preceded this session, if anything."
         },
         "prompt": {
           "anyOf": [
@@ -624,28 +459,6 @@
           "$ref": "#/$defs/SessionPrompting",
           "description": "Whether a client may send this session a message and, when it may not, the reason to show instead of a composer."
         },
-        "replayed_from_session_id": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Identifier of the original session this one was replayed from, if it was started via replay.",
-          "title": "Replayed From Session Id"
-        },
-        "resolved_budget_cents": {
-          "description": "The spend budget resolved for this session, in cents.",
-          "title": "Resolved Budget Cents",
-          "type": "integer"
-        },
-        "resolved_budget_source": {
-          "$ref": "#/$defs/BudgetSource",
-          "description": "Where the resolved budget came from."
-        },
         "sandbox_id": {
           "anyOf": [
             {
@@ -685,11 +498,11 @@
           "description": "Lifecycle state of the durable conversation, or null for sessions without one."
         },
         "source": {
-          "$ref": "#/$defs/AgentSessionSource",
+          "$ref": "#/$defs/SessionSource",
           "description": "Where the session came from (e.g. react, manual, api, cli, mention, cron, laptop)."
         },
         "status": {
-          "$ref": "#/$defs/AgentSessionStatus",
+          "$ref": "#/$defs/SessionStatus",
           "description": "Execution status of the session."
         },
         "status_reason": {
@@ -705,44 +518,9 @@
           "description": "Human-readable reason for the current status, when there is one.",
           "title": "Status Reason"
         },
-        "stopped_at": {
-          "anyOf": [
-            {
-              "format": "date-time",
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "When a stop was requested, if one was.",
-          "title": "Stopped At"
-        },
-        "stopped_by": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "GitHub account id of the user who stopped the session, if known.",
-          "title": "Stopped By"
-        },
-        "stopped_by_user": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/GithubAccountSnippet"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "The GitHub user who stopped the session, if it was stopped."
+        "stopped": {
+          "$ref": "#/$defs/SessionStopped",
+          "description": "The stop request, if the session was stopped."
         },
         "surface": {
           "anyOf": [
@@ -756,40 +534,9 @@
           "default": null,
           "description": "The public status projection; null for laptop-synced sessions."
         },
-        "tokens_cache_creation": {
-          "default": 0,
-          "description": "Tokens written to the prompt cache.",
-          "title": "Tokens Cache Creation",
-          "type": "integer"
-        },
-        "tokens_cache_read": {
-          "default": 0,
-          "description": "Tokens read from the prompt cache.",
-          "title": "Tokens Cache Read",
-          "type": "integer"
-        },
-        "tokens_input": {
-          "default": 0,
-          "description": "Input tokens used.",
-          "title": "Tokens Input",
-          "type": "integer"
-        },
-        "tokens_model": {
-          "description": "The model the token counts are attributed to.",
-          "title": "Tokens Model",
-          "type": "string"
-        },
-        "tokens_output": {
-          "default": 0,
-          "description": "Output tokens used.",
-          "title": "Tokens Output",
-          "type": "integer"
-        },
-        "tokens_total": {
-          "default": 0,
-          "description": "Total tokens used by the session.",
-          "title": "Tokens Total",
-          "type": "integer"
+        "tokens": {
+          "$ref": "#/$defs/SessionTokens",
+          "description": "The tokens the session spent and the model they went to. `total` includes the prompt-cache lanes."
         },
         "updated_at": {
           "description": "When the session was last updated.",
@@ -824,17 +571,13 @@
         }
       },
       "required": [
-        "attributed_user",
-        "attribution_id",
-        "attribution_type",
+        "attribution",
+        "budget",
         "client_version",
         "config_id",
         "config_override",
         "context_repository",
-        "cost_fee",
-        "cost_sandbox_cpu",
-        "cost_sandbox_memory",
-        "cost_tokens",
+        "cost",
         "created_at",
         "default_resolution",
         "exit_status",
@@ -845,29 +588,18 @@
         "live_summary",
         "metadata",
         "output_prs",
-        "parent_kind",
-        "parent_session_id",
+        "parent",
         "prompt",
         "prompting",
-        "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",
+        "stopped",
         "surface",
-        "tokens_cache_creation",
-        "tokens_cache_read",
-        "tokens_input",
-        "tokens_model",
-        "tokens_output",
-        "tokens_total",
+        "tokens",
         "updated_at",
         "webhook_id",
         "webhook_type"
@@ -875,6 +607,140 @@
       "title": "Session",
       "type": "object"
     },
+    "SessionAttribution": {
+      "description": "The principal a session is attributed to: what kind, its id, and \u2014 when\nthe kind is a GitHub user \u2014 the resolved display snippet.",
+      "properties": {
+        "id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Identifier of the principal the session is attributed to.",
+          "title": "Id"
+        },
+        "type": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/AttributionType"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Kind of principal the session is attributed to (e.g. a GitHub user or an API key)."
+        },
+        "user": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/GithubAccountSnippet"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The GitHub user the session is attributed to, resolved at read time. Null when the attribution is not a GitHub user."
+        }
+      },
+      "required": [
+        "id",
+        "type",
+        "user"
+      ],
+      "title": "SessionAttribution",
+      "type": "object"
+    },
+    "SessionBudget": {
+      "description": "The spend budget actually enforced for this session, and which layer of\nthe cascade set it.",
+      "properties": {
+        "cents": {
+          "default": 0,
+          "description": "The spend budget resolved for this session, in cents.",
+          "title": "Cents",
+          "type": "integer"
+        },
+        "source": {
+          "$ref": "#/$defs/BudgetSource",
+          "default": "account",
+          "description": "Where the resolved budget came from."
+        }
+      },
+      "required": [
+        "cents",
+        "source"
+      ],
+      "title": "SessionBudget",
+      "type": "object"
+    },
+    "SessionCost": {
+      "description": "What a session (or one turn of it) cost, in millicents.\n\n`llm` is deliberately NOT called `tokens`: it would sit beside the `tokens`\nobject and read as \"the token count's cost\" rather than \"the cost of the\nLLM leg\".",
+      "properties": {
+        "fee": {
+          "default": 0,
+          "description": "Platform fee in millicents.",
+          "title": "Fee",
+          "type": "integer"
+        },
+        "llm": {
+          "default": 0,
+          "description": "LLM spend in millicents.",
+          "title": "Llm",
+          "type": "integer"
+        },
+        "sandbox_cpu": {
+          "default": 0,
+          "description": "Sandbox CPU spend in millicents.",
+          "title": "Sandbox Cpu",
+          "type": "integer"
+        },
+        "sandbox_memory": {
+          "default": 0,
+          "description": "Sandbox memory spend in millicents.",
+          "title": "Sandbox Memory",
+          "type": "integer"
+        },
+        "total": {
+          "default": 0,
+          "description": "The grand total in millicents: llm + sandbox_cpu + sandbox_memory + fee.",
+          "title": "Total",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "fee",
+        "llm",
+        "sandbox_cpu",
+        "sandbox_memory",
+        "total"
+      ],
+      "title": "SessionCost",
+      "type": "object"
+    },
+    "SessionExitStatus": {
+      "description": "Why a terminal agent session ended \u2014 a finer-grained reason than `status`.\n\n`status` (SessionStatus) 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",
+        "missing_sandbox_variables",
+        "cancelled",
+        "interrupted",
+        "error",
+        "stopped"
+      ],
+      "title": "SessionExitStatus",
+      "type": "string"
+    },
     "SessionFrame": {
       "description": "A last-writer-wins snapshot of the session \u2014 the only way status,\nstate, and cost updates arrive. Resent whole on any field change.",
       "properties": {
@@ -1037,6 +903,106 @@
       "title": "SessionMessageStatus",
       "type": "string"
     },
+    "SessionParent": {
+      "description": "The ONE \"preceded-by\" chain: the predecessor session and how this one\nrelates to it. Not a parent that orchestrates children \u2014 a session never\nspawns sub-sessions.",
+      "properties": {
+        "kind": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ParentKind"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "How this session relates to its parent session, if any."
+        },
+        "replayed_from_session_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Identifier of the original session this one was replayed from, if it was started via replay.",
+          "title": "Replayed From Session Id"
+        },
+        "session_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Identifier of the parent session that spawned this one, if any.",
+          "title": "Session Id"
+        }
+      },
+      "required": [
+        "kind",
+        "replayed_from_session_id",
+        "session_id"
+      ],
+      "title": "SessionParent",
+      "type": "object"
+    },
+    "SessionPr": {
+      "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": "SessionPr",
+      "type": "object"
+    },
     "SessionPrompting": {
       "description": "The prompt-affordance projection. `enabled` answers \"would a send work\",\nand when it wouldn't, `blocked_reason` + `detail` say why.\n\n`surface_name` is set only for MENTION_SURFACE, naming where to reply.",
       "properties": {
@@ -1253,8 +1219,21 @@
       "title": "SessionRecord",
       "type": "object"
     },
+    "SessionSource": {
+      "enum": [
+        "react",
+        "manual",
+        "api",
+        "cli",
+        "mention",
+        "cron",
+        "laptop"
+      ],
+      "title": "SessionSource",
+      "type": "string"
+    },
     "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.",
+      "description": "Lifecycle of a keyed (multi-turn) session \u2014 the durable conversation.\nDistinct from SessionStatus, 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",
@@ -1263,6 +1242,71 @@
       "title": "SessionState",
       "type": "string"
     },
+    "SessionStatus": {
+      "enum": [
+        "scheduled",
+        "creating_sandbox",
+        "running",
+        "retrying",
+        "completed",
+        "error",
+        "cancelled",
+        "stopped"
+      ],
+      "title": "SessionStatus",
+      "type": "string"
+    },
+    "SessionStopped": {
+      "description": "The stop request, if there was one: when, by which GitHub account id,\nand that account resolved to a display snippet.",
+      "properties": {
+        "at": {
+          "anyOf": [
+            {
+              "format": "date-time",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "When a stop was requested, if one was.",
+          "title": "At"
+        },
+        "by": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "GitHub account id of the user who stopped the session, if known.",
+          "title": "By"
+        },
+        "by_user": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/GithubAccountSnippet"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The GitHub user who stopped the session, resolved at read time."
+        }
+      },
+      "required": [
+        "at",
+        "by",
+        "by_user"
+      ],
+      "title": "SessionStopped",
+      "type": "object"
+    },
     "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": {
@@ -1306,6 +1350,57 @@
       "title": "SessionSurface",
       "type": "object"
     },
+    "SessionTokens": {
+      "description": "The token counts a session (or turn) spent, and the model they went to.\n\n`total` INCLUDES the cache lanes, unlike the old flat `tokens_total` which\ncounted input+output+thinking only and left callers to add cache reads and\nwrites back themselves (the deleted `tokensTotalAll` helper). Cache tokens\ndominate an agent run's token bill, so a \"total\" that omits them is the\nwrong default and produced two competing totals in the dashboard.",
+      "properties": {
+        "cache_creation": {
+          "default": 0,
+          "description": "Tokens written to the prompt cache.",
+          "title": "Cache Creation",
+          "type": "integer"
+        },
+        "cache_read": {
+          "default": 0,
+          "description": "Tokens read from the prompt cache.",
+          "title": "Cache Read",
+          "type": "integer"
+        },
+        "input": {
+          "default": 0,
+          "description": "Input tokens used.",
+          "title": "Input",
+          "type": "integer"
+        },
+        "model": {
+          "default": "",
+          "description": "The model the token counts are attributed to.",
+          "title": "Model",
+          "type": "string"
+        },
+        "output": {
+          "default": 0,
+          "description": "Output tokens used.",
+          "title": "Output",
+          "type": "integer"
+        },
+        "total": {
+          "default": 0,
+          "description": "Total tokens consumed, INCLUDING the prompt-cache reads and writes \u2014 the same basis the token cost is priced on.",
+          "title": "Total",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "cache_creation",
+        "cache_read",
+        "input",
+        "model",
+        "output",
+        "total"
+      ],
+      "title": "SessionTokens",
+      "type": "object"
+    },
     "SnapshotFrame": {
       "description": "The first frame after the stream connects: the session plus its open\ninbox. Records always arrive separately via records_append frames.",
       "properties": {