@ellipsis-dev/sdk 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ellipsis-dev/sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "TypeScript SDK for the Ellipsis agents platform: /v1 REST types + client, the session stream WebSocket client, and the session transcript store.",
   "license": "MIT",
   "type": "module",

package/schema/frames.schema.json

@@ -268,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": [
@@ -358,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.",
@@ -486,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": [
@@ -528,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": [
             {
@@ -609,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": [
@@ -660,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.",
@@ -728,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",
@@ -749,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"
@@ -779,6 +607,121 @@
       "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": [
@@ -960,6 +903,56 @@
       "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": {
@@ -1263,6 +1256,57 @@
       "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": {