@ellipsis-dev/sdk 0.9.0 → 0.10.0

package/schema/openapi.v1.json

@@ -480,6 +480,37 @@
         "title": "AgentConfigEllipsis",
         "type": "object"
       },
+      "AgentConfigEllipsisPermissions": {
+        "additionalProperties": {
+          "anyOf": [
+            {
+              "$ref": "#/components/schemas/Level"
+            },
+            {
+              "$ref": "#/components/schemas/EllipsisGrant"
+            },
+            {
+              "items": {
+                "anyOf": [
+                  {
+                    "$ref": "#/components/schemas/Level"
+                  },
+                  {
+                    "$ref": "#/components/schemas/EllipsisGrant"
+                  }
+                ]
+              },
+              "type": "array"
+            }
+          ]
+        },
+        "description": "`permissions.ellipsis` as a map: resource \u2192 level | grant | list of\ngrants. Levels are hierarchical (read < write < delete), so `write`\nincludes `read`. An unlisted resource is denied. The whole block is\nintersected with the platform's sandbox ceiling at token mint \u2014 it can\nnarrow what a sandbox token may do, never exceed it.",
+        "propertyNames": {
+          "$ref": "#/components/schemas/Resource"
+        },
+        "title": "AgentConfigEllipsisPermissions",
+        "type": "object"
+      },
       "AgentConfigEnvironment": {
         "additionalProperties": false,
         "description": "Everything about the environment (the sandbox) the agent runs in: which\n`repositories` are cloned into it, which environment `variables` it gets,\nits `compute` sizing, how its `image` is customized, and lifecycle `hooks`.\nWhat the agent may *do* from that environment is the top-level\n`permissions:` block, not this one.\n\nEach `variables` entry names a variable to inject; with an inline `value` it\nis hardcoded, without one it is resolved from the account's sandbox-secrets\nstore. Only the named variables reach this agent; the rest of the account's\nstored variables never do. This is how a config brings in the config and\ncredentials a custom CLI needs.",
@@ -824,14 +855,21 @@
       },
       "AgentConfigPermissions": {
         "additionalProperties": false,
-        "description": "What the agent is allowed to touch, per credential the platform mints\ninto its sandbox. Distinct from `environment:`, which is where the agent\nruns; this is what it may do from there.\n\n`ellipsis` scopes the sandbox's Ellipsis API token\n(`ELLIPSIS_API_TOKEN`, what the in-sandbox `agent` CLI authenticates\nwith). Only full access exists today \u2014 `true` or the string `all`, both\nmeaning the token may call any Ellipsis API a sandbox token can. The key\nis declarative for now; it reserves the spot for narrowing later, and\nanything other than true/`all` (including `false`) fails validation.\n\n`github` scopes the sandbox's GitHub installation token (`GH_TOKEN`) \u2014\nsee `AgentConfigGithubPermissions`. GitHub enforces it at mint time.",
+        "description": "What the agent is allowed to touch, per credential the platform mints\ninto its sandbox. Distinct from `environment:`, which is where the agent\nruns; this is what it may do from there.\n\n`ellipsis` scopes the sandbox's Ellipsis API token\n(`ELLIPSIS_API_TOKEN`, what the in-sandbox `agent` CLI authenticates\nwith). `true` / the string `all` (the default) grant the full sandbox\nceiling \u2014 everything a sandbox token can ever do. A map narrows it per\nresource (see `AgentConfigEllipsisPermissions`); the minted token carries\nthe intersection, so a config can only ever reduce access. `false` fails\nvalidation \u2014 an agent with no API token cannot report its own progress.\n\n`github` scopes the sandbox's GitHub installation token (`GH_TOKEN`) \u2014\nsee `AgentConfigGithubPermissions`. GitHub enforces it at mint time.",
         "properties": {
           "ellipsis": {
-            "default": true,
-            "enum": [
-              true,
-              "all"
+            "anyOf": [
+              {
+                "enum": [
+                  true,
+                  "all"
+                ]
+              },
+              {
+                "$ref": "#/components/schemas/AgentConfigEllipsisPermissions"
+              }
             ],
+            "default": true,
             "title": "Ellipsis"
           },
           "github": {
@@ -2333,6 +2371,34 @@
         "title": "EffortLevel",
         "type": "string"
       },
+      "EllipsisGrant": {
+        "additionalProperties": false,
+        "description": "One grant entry: a level, optionally narrowed to instances whose\nnatural key (a file's name, a memory's path, a secret's name, a config's\nname, a session's id) matches any of the `match` globs.",
+        "properties": {
+          "level": {
+            "$ref": "#/components/schemas/Level"
+          },
+          "match": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Match"
+          }
+        },
+        "required": [
+          "level"
+        ],
+        "title": "EllipsisGrant",
+        "type": "object"
+      },
       "ErrorInfo": {
         "properties": {
           "code": {
@@ -3676,6 +3742,16 @@
         "title": "JiraIntegrationSummary",
         "type": "object"
       },
+      "Level": {
+        "description": "What may be done to a resource. Strictly ordered: a grant at one level\nincludes every level below it (write-only would be a phantom capability \u2014\nno real client can create what it cannot read back).",
+        "enum": [
+          "read",
+          "write",
+          "delete"
+        ],
+        "title": "Level",
+        "type": "string"
+      },
       "LinearIntegrationSummary": {
         "description": "The account's connected Linear organization and its teams.",
         "properties": {
@@ -5127,6 +5203,25 @@
         "title": "ResolvedReviewScope",
         "type": "object"
       },
+      "Resource": {
+        "description": "Everything a credential can be granted access to, one value per /v1\nresource family. `TOKENS` is reserved for the future token-management\nroutes; nothing maps to it yet.",
+        "enum": [
+          "account",
+          "alerts",
+          "sessions",
+          "files",
+          "memories",
+          "reviews",
+          "configs",
+          "defaults",
+          "secrets",
+          "templates",
+          "integrations",
+          "tokens"
+        ],
+        "title": "Resource",
+        "type": "string"
+      },
       "Review": {
         "description": "One code review: one pipeline iteration over one commit range of a pull\nrequest.\n\n`review_body`, `findings`, and `counters` are produced as each stage\nsession finishes \u2014 while a review is running they are null/empty. Stream a\nstage's session to follow it live, then re-fetch the review.",
         "properties": {
@@ -6612,39 +6707,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": "#/components/schemas/GithubAccountSnippet"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The GitHub user the session is attributed to, when the attribution is a GitHub user."
-          },
-          "attribution_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Identifier of the principal the session is attributed to.",
-            "title": "Attribution Id"
+          "attribution": {
+            "$ref": "#/components/schemas/SessionAttribution",
+            "description": "The principal this session is attributed to."
           },
-          "attribution_type": {
-            "anyOf": [
-              {
-                "$ref": "#/components/schemas/AttributionType"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Kind of principal the session is attributed to (e.g. a GitHub user or an API key)."
+          "budget": {
+            "$ref": "#/components/schemas/SessionBudget",
+            "description": "The spend budget enforced for this session."
           },
           "client_version": {
             "anyOf": [
@@ -6695,28 +6764,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": "#/components/schemas/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.",
@@ -6817,28 +6867,9 @@
             "description": "Pull requests the session created or updated.",
             "title": "Output Prs"
           },
-          "parent_kind": {
-            "anyOf": [
-              {
-                "$ref": "#/components/schemas/ParentKind"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "How this session relates to its parent session, if any."
-          },
-          "parent_session_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "Identifier of the parent session that spawned this one, if any.",
-            "title": "Parent Session Id"
+          "parent": {
+            "$ref": "#/components/schemas/SessionParent",
+            "description": "What preceded this session, if anything."
           },
           "prompt": {
             "anyOf": [
@@ -6856,27 +6887,6 @@
             "$ref": "#/components/schemas/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"
-              }
-            ],
-            "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": "#/components/schemas/BudgetSource",
-            "description": "Where the resolved budget came from."
-          },
           "sandbox_id": {
             "anyOf": [
               {
@@ -6932,41 +6942,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"
-              }
-            ],
-            "description": "When a stop was requested, if one was.",
-            "title": "Stopped At"
-          },
-          "stopped_by": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "GitHub account id of the user who stopped the session, if known.",
-            "title": "Stopped By"
-          },
-          "stopped_by_user": {
-            "anyOf": [
-              {
-                "$ref": "#/components/schemas/GithubAccountSnippet"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The GitHub user who stopped the session, if it was stopped."
+          "stopped": {
+            "$ref": "#/components/schemas/SessionStopped",
+            "description": "The stop request, if the session was stopped."
           },
           "surface": {
             "anyOf": [
@@ -6979,40 +6957,9 @@
             ],
             "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": "#/components/schemas/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.",
@@ -7050,16 +6997,108 @@
           "updated_at",
           "harness",
           "source",
-          "cost_tokens",
-          "tokens_model",
-          "resolved_budget_cents",
-          "resolved_budget_source",
           "status",
           "prompting"
         ],
         "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"
+              }
+            ],
+            "description": "Identifier of the principal the session is attributed to.",
+            "title": "Id"
+          },
+          "type": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/AttributionType"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Kind of principal the session is attributed to (e.g. a GitHub user or an API key)."
+          },
+          "user": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/GithubAccountSnippet"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The GitHub user the session is attributed to, resolved at read time. Null when the attribution is not a GitHub 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": "#/components/schemas/BudgetSource",
+            "default": "account",
+            "description": "Where the resolved budget came from."
+          }
+        },
+        "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"
+          }
+        },
+        "title": "SessionCost",
+        "type": "object"
+      },
       "SessionExecution": {
         "description": "One runtime attempt of a session \u2014 the initial start, a cold wake of a\ndurable conversation, or an infrastructure retry \u2014 including the launch\ncontext the model was actually given.",
         "properties": {
@@ -7390,6 +7429,48 @@
         "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": "#/components/schemas/ParentKind"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "How this session relates to its parent session, if any."
+          },
+          "replayed_from_session_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "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"
+              }
+            ],
+            "description": "Identifier of the parent session that spawned this one, if any.",
+            "title": "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": {
@@ -7827,6 +7908,49 @@
         "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"
+              }
+            ],
+            "description": "When a stop was requested, if one was.",
+            "title": "At"
+          },
+          "by": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "GitHub account id of the user who stopped the session, if known.",
+            "title": "By"
+          },
+          "by_user": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/GithubAccountSnippet"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The GitHub user who stopped the session, resolved at read time."
+          }
+        },
+        "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": {
@@ -7870,6 +7994,49 @@
         "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"
+          }
+        },
+        "title": "SessionTokens",
+        "type": "object"
+      },
       "SessionsListResponse": {
         "description": "A page of sessions in the lean wire shape.",
         "properties": {