@ellipsis-dev/sdk 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ellipsis-dev/sdk",
-  "version": "0.36.0",
+  "version": "0.37.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/collection_frames.schema.json

@@ -501,7 +501,7 @@
             }
           ],
           "default": null,
-          "description": "The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.",
+          "description": "The initial user message, passed verbatim. Omit to start an interactive session with no message, waiting for one.",
           "title": "Prompt"
         },
         "settings": {
@@ -541,7 +541,7 @@
             }
           ],
           "default": null,
-          "description": "Reasoning effort for every turn. Omit to use the model default."
+          "description": "Reasoning effort for every message. Omit to use the model default."
         },
         "model": {
           "description": "The model the session runs on: a Responses-capable id from the models table. Required.",
@@ -558,7 +558,7 @@
             }
           ],
           "default": null,
-          "description": "The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.",
+          "description": "The initial user message, passed verbatim. Omit to start an interactive session with no message, waiting for one.",
           "title": "Prompt"
         }
       },
@@ -1159,6 +1159,30 @@
       "title": "EnvironmentVariable",
       "type": "object"
     },
+    "ErrorReason": {
+      "description": "Why a message failed, was stopped, or was cancelled.",
+      "enum": [
+        "error",
+        "tool_call_failed",
+        "budget_hit",
+        "payment_required",
+        "blocked",
+        "contact_email_required",
+        "lifecycle_hook_failed",
+        "missing_repo_access",
+        "missing_token_permissions",
+        "missing_environment_variables",
+        "missing_github_integration",
+        "agent_unavailable",
+        "upstream_unavailable",
+        "unsupported_configuration",
+        "execution_disabled",
+        "interrupted",
+        "stopped"
+      ],
+      "title": "ErrorReason",
+      "type": "string"
+    },
     "GeminiConfig": {
       "additionalProperties": false,
       "description": "Native options supported by the current Gemini CLI adapter.",
@@ -1178,7 +1202,7 @@
             }
           ],
           "default": null,
-          "description": "The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.",
+          "description": "The initial user message, passed verbatim. Omit to start an interactive session with no message, waiting for one.",
           "title": "Prompt"
         }
       },
@@ -3512,7 +3536,7 @@
           ]
         }
       ],
-      "description": "An agent session: one conversation with an agent. Returned by\n`GET /v1/sessions/{id}` and carried by the session stream's\n`session`/`snapshot` frames; REST and stream never disagree about what a\nsession looks like.",
+      "description": "An agent session: one conversation with an agent. Returned by\n`GET /v1/sessions/{id}` and carried by the session stream's\n`session` frames; REST and stream never disagree about what a\nsession looks like.",
       "properties": {
         "agent": {
           "anyOf": [
@@ -3590,6 +3614,18 @@
           "$ref": "#/$defs/SessionEnvironment",
           "description": "The full environment configuration frozen when the session was created, with the saved environment's id and how it was chosen."
         },
+        "error": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SessionError"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Why the last message failed, was stopped, or was cancelled; null otherwise."
+        },
         "event": {
           "anyOf": [
             {
@@ -3717,7 +3753,7 @@
             }
           ],
           "default": null,
-          "description": "The session's structured output: the `json_schema` the agent must satisfy and, once a turn has submitted it, the `result`."
+          "description": "The session's structured output: the `json_schema` the agent must satisfy and, once the agent has submitted it, the `result`."
         },
         "parent": {
           "anyOf": [
@@ -3747,6 +3783,10 @@
           "$ref": "#/$defs/SessionSource",
           "description": "Where the session came from (e.g. react, web, api, cli, mention, cron)."
         },
+        "status": {
+          "$ref": "#/$defs/SessionStatus",
+          "description": "Where the session is. A message you sent is answered once the status is `idle` or `closed`; its `message_ended` record in GET /v1/sessions/{id}/records says how."
+        },
         "summary": {
           "anyOf": [
             {
@@ -3763,18 +3803,6 @@
           "$ref": "#/$defs/Tokens",
           "description": "The tokens the session has used so far."
         },
-        "turn": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/SessionTurn"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "The turn in progress, or the latest one when none is running. Null until the session has a message. Wait on it: the message you sent is answered when the turn with your message's `turn_id` reaches a final status."
-        },
         "updated_at": {
           "description": "When the session was last updated.",
           "format": "date-time",
@@ -3793,6 +3821,7 @@
         "cost",
         "created_at",
         "environment",
+        "error",
         "event",
         "gemini",
         "git",
@@ -3804,9 +3833,9 @@
         "permissions",
         "skills",
         "source",
+        "status",
         "summary",
         "tokens",
-        "turn",
         "updated_at"
       ],
       "title": "Session",
@@ -4123,7 +4152,7 @@
       "description": "Whether the session can take more messages, and how quickly it would\nanswer one.",
       "properties": {
         "interactive": {
-          "description": "Whether the session stays open after its first turn.",
+          "description": "Whether the session stays open after its first message is answered.",
           "title": "Interactive",
           "type": "boolean"
         },
@@ -4131,10 +4160,6 @@
           "$ref": "#/$defs/SessionPrompting",
           "description": "The session's policy for direct messages. Caller authorization and message validation are checked separately."
         },
-        "state": {
-          "$ref": "#/$defs/SessionState",
-          "description": "`open` while the session can take messages; `closed` is permanent."
-        },
         "warm": {
           "description": "Whether an agent is ready to answer the next message right away. When false, the next message first prepares an environment, which takes longer. A hint only; clients need no logic on it.",
           "title": "Warm",
@@ -4144,7 +4169,6 @@
       "required": [
         "interactive",
         "prompting",
-        "state",
         "warm"
       ],
       "title": "SessionConversation",
@@ -4156,7 +4180,7 @@
       "properties": {
         "interactive": {
           "default": true,
-          "description": "Whether the session stays open after its first turn. Defaults to true; false runs once and requires a prompt. Requires the model's interactive capability when true. Direct message acceptance is reported separately in conversation.prompting.",
+          "description": "Whether the session stays open after its first message is answered. Defaults to true; false runs once and requires a prompt. Requires the model's interactive capability when true. Direct message acceptance is reported separately in conversation.prompting.",
           "title": "Interactive",
           "type": "boolean"
         }
@@ -4265,6 +4289,34 @@
       "title": "SessionEnvironment",
       "type": "object"
     },
+    "SessionError": {
+      "description": "Why the last message failed, was stopped, or was cancelled. Cleared\nwhen the next message starts.",
+      "properties": {
+        "detail": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "A human-readable explanation.",
+          "title": "Detail"
+        },
+        "reason": {
+          "$ref": "#/$defs/ErrorReason",
+          "description": "What went wrong."
+        }
+      },
+      "required": [
+        "detail",
+        "reason"
+      ],
+      "title": "SessionError",
+      "type": "object"
+    },
     "SessionEventActor": {
       "description": "The event's initiator, when known; never inferred from resource ownership.",
       "properties": {
@@ -4568,7 +4620,7 @@
       "type": "object"
     },
     "SessionOutput": {
-      "description": "Structured output on the wire: the contract and, when a turn has\nsubmitted one, the payload. `result` is None while the session runs and\nwhen no turn submitted anything; it is the agent's own JSON, in the\nshape of `json_schema`.",
+      "description": "Structured output on the wire: the contract and, when the agent has\nsubmitted one, the payload. `result` is None while the session runs and\nwhen the agent submitted nothing; it is the agent's own JSON, in the\nshape of `json_schema`.",
       "properties": {
         "json_schema": {
           "additionalProperties": true,
@@ -4587,7 +4639,7 @@
             }
           ],
           "default": null,
-          "description": "The payload the agent submitted, or null until a turn submits one.",
+          "description": "The payload the agent submitted, or null until it submits one.",
           "title": "Result"
         }
       },
@@ -4687,44 +4739,18 @@
       "title": "SessionSource",
       "type": "string"
     },
-    "SessionState": {
-      "description": "Whether the conversation can still take messages. `closed` is permanent:\na session with interactive false closes when its turn ends, and a conversation closes\nafter its closing message's turn.",
+    "SessionStatus": {
+      "description": "Where the session is. `queued` while a message waits for a worker,\n`preparing` while its environment is set up, `running` while the agent\nworks, `idle` when every message has been answered and the session can\ntake another, and `closed` when it can take no more. `closed` is\npermanent.",
       "enum": [
-        "open",
+        "queued",
+        "preparing",
+        "running",
+        "idle",
         "closed"
       ],
-      "title": "SessionState",
+      "title": "SessionStatus",
       "type": "string"
     },
-    "SessionStopped": {
-      "description": "When a stop was requested and the GitHub user who requested it.",
-      "properties": {
-        "at": {
-          "description": "When a stop was requested.",
-          "format": "date-time",
-          "title": "At",
-          "type": "string"
-        },
-        "by": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/GithubAccountSnippet"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "The GitHub user who stopped the session, resolved at read time. Null if the user is unknown or unavailable."
-        }
-      },
-      "required": [
-        "at",
-        "by"
-      ],
-      "title": "SessionStopped",
-      "type": "object"
-    },
     "SessionSummary": {
       "description": "A live one-line summary of what the session is doing, refreshed\nevery few steps while it runs.",
       "properties": {
@@ -4755,119 +4781,6 @@
       "title": "SessionSummary",
       "type": "object"
     },
-    "SessionTurn": {
-      "description": "One message and the agent's answer to it. A turn is `queued` from the\nmoment its message is received, `preparing` while its environment is set\nup, `running` while the agent works, then `completed`, `failed`,\n`stopped`, or `cancelled`.",
-      "properties": {
-        "cost": {
-          "$ref": "#/$defs/Cost",
-          "description": "What the turn cost so far, in millicents, broken down by leg."
-        },
-        "created_at": {
-          "description": "When the turn's message was received.",
-          "format": "date-time",
-          "title": "Created At",
-          "type": "string"
-        },
-        "detail": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "A human-readable explanation of a failed, stopped, or cancelled turn, or of why a queued turn waits.",
-          "title": "Detail"
-        },
-        "ended_at": {
-          "anyOf": [
-            {
-              "format": "date-time",
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "When the turn reached its final status.",
-          "title": "Ended At"
-        },
-        "id": {
-          "description": "Unique identifier of the turn.",
-          "title": "Id",
-          "type": "string"
-        },
-        "index": {
-          "description": "Position in the session, starting at 0.",
-          "title": "Index",
-          "type": "integer"
-        },
-        "reason": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/TurnReason"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Why the turn failed or was cancelled; null on every other status."
-        },
-        "started_at": {
-          "anyOf": [
-            {
-              "format": "date-time",
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "When the agent started on the message.",
-          "title": "Started At"
-        },
-        "status": {
-          "$ref": "#/$defs/TurnStatus",
-          "description": "Where the turn is."
-        },
-        "stopped": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/SessionStopped"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "When and by whom a stop was requested; null when none was."
-        },
-        "tokens": {
-          "$ref": "#/$defs/Tokens",
-          "description": "The tokens the turn spent and the model they went to."
-        }
-      },
-      "required": [
-        "cost",
-        "created_at",
-        "detail",
-        "ended_at",
-        "id",
-        "index",
-        "reason",
-        "started_at",
-        "status",
-        "stopped",
-        "tokens"
-      ],
-      "title": "SessionTurn",
-      "type": "object"
-    },
     "SettingsRef": {
       "additionalProperties": false,
       "description": "A Claude Code settings.json read from a repository and applied to the\nsession. It adds permission rules and other Claude Code settings; rules the\nplatform sets stay in force. Supported models list `settings` in\n`/v1/account/models`.",
@@ -5127,43 +5040,6 @@
       "title": "Tokens",
       "type": "object"
     },
-    "TurnReason": {
-      "description": "Why a turn failed or was cancelled. Null on every other outcome.",
-      "enum": [
-        "error",
-        "tool_call_failed",
-        "budget_hit",
-        "payment_required",
-        "blocked",
-        "contact_email_required",
-        "lifecycle_hook_failed",
-        "missing_repo_access",
-        "missing_token_permissions",
-        "missing_environment_variables",
-        "missing_github_integration",
-        "agent_unavailable",
-        "upstream_unavailable",
-        "unsupported_configuration",
-        "execution_disabled",
-        "interrupted"
-      ],
-      "title": "TurnReason",
-      "type": "string"
-    },
-    "TurnStatus": {
-      "description": "Where one turn is: waiting, preparing, being answered, or over.\n\n`queued` turns wait to start, behind another turn or for a free session\nslot on the account. `preparing` turns wait while the environment is set\nup. `stopped` and `cancelled` are their own outcomes; `reason` explains a\n`failed` or `cancelled` turn.",
-      "enum": [
-        "queued",
-        "preparing",
-        "running",
-        "completed",
-        "failed",
-        "stopped",
-        "cancelled"
-      ],
-      "title": "TurnStatus",
-      "type": "string"
-    },
     "VMExecutionResponse": {
       "properties": {
         "cache_tier": {