@ellipsis-dev/sdk 0.36.0 → 0.38.0

package/schema/lifecycle.schema.json

@@ -1,8 +1,49 @@
 {
   "$defs": {
+    "Cost": {
+      "description": "What something cost, in millicents.",
+      "properties": {
+        "charged": {
+          "default": 0,
+          "description": "What Ellipsis charged to credit, in millicents. It is everything except subscription tokens.",
+          "title": "Charged",
+          "type": "integer"
+        },
+        "cpu": {
+          "default": 0,
+          "description": "CPU spend in millicents.",
+          "title": "Cpu",
+          "type": "integer"
+        },
+        "fee": {
+          "default": 0,
+          "description": "Platform fee in millicents.",
+          "title": "Fee",
+          "type": "integer"
+        },
+        "llm": {
+          "$ref": "#/$defs/LlmCost",
+          "description": "LLM token cost, in total and by model, split by who paid."
+        },
+        "memory": {
+          "default": 0,
+          "description": "Memory spend in millicents.",
+          "title": "Memory",
+          "type": "integer"
+        },
+        "total": {
+          "default": 0,
+          "description": "Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee, and it is what the budget caps.",
+          "title": "Total",
+          "type": "integer"
+        }
+      },
+      "title": "Cost",
+      "type": "object"
+    },
     "EnvironmentOutputPayload": {
       "additionalProperties": true,
-      "description": "environment_output: one chunk of output from preparing the environment,\nincluding the customer's own hooks. Many fire per turn; `chunk` orders them\nwithin a step.",
+      "description": "environment_output: one chunk of output from preparing the environment,\nincluding the customer's own hooks. Many fire per message; `chunk` orders\nthem within a step.",
       "properties": {
         "chunk": {
           "title": "Chunk",
@@ -132,141 +173,277 @@
       "title": "EnvironmentReadyPayload",
       "type": "object"
     },
-    "MessageDeliveredPayload": {
-      "additionalProperties": true,
-      "description": "message_delivered: the agent started on the message.",
+    "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"
+    },
+    "LlmCost": {
+      "description": "What LLM tokens cost, in total and by model.",
       "properties": {
-        "message_id": {
-          "title": "Message Id",
-          "type": "string"
+        "all": {
+          "$ref": "#/$defs/LlmCostSplit",
+          "description": "Token cost across every model."
         },
-        "turn_id": {
-          "title": "Turn Id",
-          "type": "string"
+        "by_model": {
+          "description": "Token cost for each model that used tokens.",
+          "items": {
+            "$ref": "#/$defs/ModelLlmCostSplit"
+          },
+          "title": "By Model",
+          "type": "array"
         }
       },
-      "required": [
-        "message_id",
-        "turn_id"
-      ],
-      "title": "MessageDeliveredPayload",
+      "title": "LlmCost",
       "type": "object"
     },
-    "MessageReceivedPayload": {
-      "additionalProperties": true,
-      "description": "message_received: a message landed in the session inbox and its turn was\ncreated. `turn_id` is the turn that will answer it.",
+    "LlmCostSplit": {
+      "description": "What LLM tokens cost, in millicents, split by who paid (Ellipsis credit or the user's own subscription).",
       "properties": {
-        "author": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Author"
+        "claude_subscription": {
+          "default": 0,
+          "description": "Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.",
+          "title": "Claude Subscription",
+          "type": "integer"
         },
-        "body": {
-          "title": "Body",
-          "type": "string"
+        "codex_subscription": {
+          "default": 0,
+          "description": "Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.",
+          "title": "Codex Subscription",
+          "type": "integer"
         },
-        "closes_session": {
-          "default": false,
-          "title": "Closes Session",
-          "type": "boolean"
+        "platform": {
+          "default": 0,
+          "description": "Token cost charged to Ellipsis credit, in millicents.",
+          "title": "Platform",
+          "type": "integer"
         },
-        "message_id": {
-          "title": "Message Id",
-          "type": "string"
+        "total": {
+          "default": 0,
+          "description": "All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.",
+          "title": "Total",
+          "type": "integer"
+        }
+      },
+      "title": "LlmCostSplit",
+      "type": "object"
+    },
+    "MessageEndedPayload": {
+      "additionalProperties": true,
+      "description": "message_ended: the message was answered, or its answer failed, was\nstopped, or was cancelled. `error` is the same object as the session's\n`error`, null when the message was answered. `cost` and `tokens` are what\nanswering it spent. Messages answered together report the spend once, on\nthe last of them.",
+      "properties": {
+        "cost": {
+          "$ref": "#/$defs/Cost"
         },
-        "sender_attribution_id": {
+        "duration_ms": {
           "anyOf": [
             {
-              "type": "string"
+              "type": "integer"
             },
             {
               "type": "null"
             }
           ],
           "default": null,
-          "title": "Sender Attribution Id"
+          "title": "Duration Ms"
         },
-        "sender_attribution_type": {
+        "error": {
           "anyOf": [
             {
-              "type": "string"
+              "$ref": "#/$defs/SessionError"
             },
             {
               "type": "null"
             }
           ],
-          "default": null,
-          "title": "Sender Attribution Type"
+          "default": null
         },
-        "turn_id": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Turn Id"
+        "message_id": {
+          "title": "Message Id",
+          "type": "string"
+        },
+        "status": {
+          "title": "Status",
+          "type": "string"
+        },
+        "tokens": {
+          "$ref": "#/$defs/Tokens"
         }
       },
       "required": [
         "message_id",
-        "body"
+        "status"
       ],
-      "title": "MessageReceivedPayload",
+      "title": "MessageEndedPayload",
+      "type": "object"
+    },
+    "MessageQueuedPayload": {
+      "additionalProperties": true,
+      "description": "message_queued: the message waits because the account already has\n`sessions_alive` sessions alive, its limit.",
+      "properties": {
+        "limit": {
+          "title": "Limit",
+          "type": "integer"
+        },
+        "message_id": {
+          "title": "Message Id",
+          "type": "string"
+        },
+        "sessions_alive": {
+          "title": "Sessions Alive",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "message_id",
+        "sessions_alive",
+        "limit"
+      ],
+      "title": "MessageQueuedPayload",
       "type": "object"
     },
     "MessageRequeuedPayload": {
       "additionalProperties": true,
-      "description": "message_requeued: a turn was interrupted before answering, so the\nmessage goes back to the inbox with a new queued turn.",
+      "description": "message_requeued: the agent was interrupted before answering, so the\nmessage goes back to the inbox and starts again on a fresh environment.",
+      "properties": {
+        "message_id": {
+          "title": "Message Id",
+          "type": "string"
+        }
+      },
+      "required": [
+        "message_id"
+      ],
+      "title": "MessageRequeuedPayload",
+      "type": "object"
+    },
+    "MessageStartedPayload": {
+      "additionalProperties": true,
+      "description": "message_started: the agent started on the message.",
       "properties": {
         "message_id": {
           "title": "Message Id",
           "type": "string"
+        }
+      },
+      "required": [
+        "message_id"
+      ],
+      "title": "MessageStartedPayload",
+      "type": "object"
+    },
+    "ModelLlmCostSplit": {
+      "description": "What one model's tokens cost, in millicents, split by who paid.",
+      "properties": {
+        "claude_subscription": {
+          "default": 0,
+          "description": "Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.",
+          "title": "Claude Subscription",
+          "type": "integer"
         },
-        "requeued_turn_id": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Requeued Turn Id"
+        "codex_subscription": {
+          "default": 0,
+          "description": "Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.",
+          "title": "Codex Subscription",
+          "type": "integer"
         },
-        "turn_id": {
-          "title": "Turn Id",
+        "model": {
+          "description": "The model that used these tokens.",
+          "title": "Model",
           "type": "string"
+        },
+        "platform": {
+          "default": 0,
+          "description": "Token cost charged to Ellipsis credit, in millicents.",
+          "title": "Platform",
+          "type": "integer"
+        },
+        "total": {
+          "default": 0,
+          "description": "All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.",
+          "title": "Total",
+          "type": "integer"
         }
       },
       "required": [
-        "message_id",
-        "turn_id"
+        "model"
       ],
-      "title": "MessageRequeuedPayload",
+      "title": "ModelLlmCostSplit",
+      "type": "object"
+    },
+    "ModelTokenCounts": {
+      "description": "Token counts for one model.",
+      "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": {
+          "description": "The model that used these tokens.",
+          "title": "Model",
+          "type": "string"
+        },
+        "output": {
+          "default": 0,
+          "description": "Output tokens used.",
+          "title": "Output",
+          "type": "integer"
+        },
+        "total": {
+          "default": 0,
+          "description": "All tokens used, including prompt cache reads and writes. Token cost is priced on this.",
+          "title": "Total",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "model"
+      ],
+      "title": "ModelTokenCounts",
       "type": "object"
     },
     "SessionClosedPayload": {
       "additionalProperties": true,
-      "description": "session_closed: the conversation closed permanently.",
+      "description": "session_closed: the session closed permanently.",
       "properties": {},
       "title": "SessionClosedPayload",
       "type": "object"
     },
-    "TurnEndedPayload": {
-      "additionalProperties": true,
-      "description": "turn_ended: the turn reached its final status. `status`, `reason`, and\n`detail` match the turn on the session object.",
+    "SessionError": {
+      "description": "Why the last message failed, was stopped, or was cancelled. Cleared\nwhen the next message starts.",
       "properties": {
         "detail": {
           "anyOf": [
@@ -278,21 +455,24 @@
             }
           ],
           "default": null,
+          "description": "A human-readable explanation.",
           "title": "Detail"
         },
-        "duration_ms": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Duration Ms"
-        },
         "reason": {
+          "$ref": "#/$defs/ErrorReason",
+          "description": "What went wrong."
+        }
+      },
+      "required": [
+        "reason"
+      ],
+      "title": "SessionError",
+      "type": "object"
+    },
+    "SessionMessage": {
+      "description": "One message sent to a session.",
+      "properties": {
+        "author": {
           "anyOf": [
             {
               "type": "string"
@@ -302,72 +482,135 @@
             }
           ],
           "default": null,
-          "title": "Reason"
+          "description": "Display attribution of the message's sender.",
+          "title": "Author"
         },
-        "status": {
-          "title": "Status",
+        "body": {
+          "description": "The message text, with one `[Image #N]` placeholder per attached image.",
+          "title": "Body",
           "type": "string"
         },
-        "turn_id": {
-          "title": "Turn Id",
+        "created_at": {
+          "description": "When the message was received.",
+          "format": "date-time",
+          "title": "Created At",
           "type": "string"
         },
-        "turn_index": {
-          "title": "Turn Index",
+        "id": {
+          "description": "Unique identifier of the message.",
+          "title": "Id",
+          "type": "string"
+        },
+        "images": {
+          "description": "Images attached to the message, metadata only: index, media type, size. The bytes go to the model, never over the stream.",
+          "items": {
+            "$ref": "#/$defs/SessionMessageImage"
+          },
+          "title": "Images",
+          "type": "array"
+        },
+        "index": {
+          "description": "Position in the session, starting at 0.",
+          "title": "Index",
           "type": "integer"
+        },
+        "session_id": {
+          "description": "Identifier of the session the message belongs to.",
+          "title": "Session Id",
+          "type": "string"
         }
       },
       "required": [
-        "turn_id",
-        "turn_index",
-        "status"
+        "id",
+        "session_id",
+        "index",
+        "body",
+        "created_at"
       ],
-      "title": "TurnEndedPayload",
+      "title": "SessionMessage",
       "type": "object"
     },
-    "TurnQueuedPayload": {
-      "additionalProperties": true,
-      "description": "turn_queued: the turn waits because the account already has\n`sessions_alive` sessions alive, its limit.",
+    "SessionMessageImage": {
+      "description": "One image on a message, metadata only. `index` is the N in the\n`[Image #N]` placeholder in the message body.",
       "properties": {
-        "limit": {
-          "title": "Limit",
+        "index": {
+          "description": "1-based position: the N in `[Image #N]`.",
+          "title": "Index",
           "type": "integer"
         },
-        "sessions_alive": {
-          "title": "Sessions Alive",
-          "type": "integer"
-        },
-        "turn_id": {
-          "title": "Turn Id",
+        "media_type": {
+          "description": "The image's MIME type.",
+          "title": "Media Type",
           "type": "string"
+        },
+        "size_bytes": {
+          "description": "Size of the decoded image, in bytes.",
+          "title": "Size Bytes",
+          "type": "integer"
         }
       },
       "required": [
-        "turn_id",
-        "sessions_alive",
-        "limit"
+        "index",
+        "media_type",
+        "size_bytes"
       ],
-      "title": "TurnQueuedPayload",
+      "title": "SessionMessageImage",
       "type": "object"
     },
-    "TurnStartedPayload": {
-      "additionalProperties": true,
-      "description": "turn_started: the agent started on the turn's message.",
+    "TokenCounts": {
+      "description": "Token counts.",
       "properties": {
-        "turn_id": {
-          "title": "Turn Id",
-          "type": "string"
+        "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"
         },
-        "turn_index": {
-          "title": "Turn Index",
+        "output": {
+          "default": 0,
+          "description": "Output tokens used.",
+          "title": "Output",
+          "type": "integer"
+        },
+        "total": {
+          "default": 0,
+          "description": "All tokens used, including prompt cache reads and writes. Token cost is priced on this.",
+          "title": "Total",
           "type": "integer"
         }
       },
-      "required": [
-        "turn_id",
-        "turn_index"
-      ],
-      "title": "TurnStartedPayload",
+      "title": "TokenCounts",
+      "type": "object"
+    },
+    "Tokens": {
+      "description": "Tokens used, in total and by model.",
+      "properties": {
+        "all": {
+          "$ref": "#/$defs/TokenCounts",
+          "description": "Token counts across every model."
+        },
+        "by_model": {
+          "description": "Token counts for each model that used tokens.",
+          "items": {
+            "$ref": "#/$defs/ModelTokenCounts"
+          },
+          "title": "By Model",
+          "type": "array"
+        }
+      },
+      "title": "Tokens",
       "type": "object"
     }
   },
@@ -383,39 +626,35 @@
     "environment_ready": {
       "$ref": "#/$defs/EnvironmentReadyPayload"
     },
-    "message_delivered": {
-      "$ref": "#/$defs/MessageDeliveredPayload"
+    "message": {
+      "$ref": "#/$defs/SessionMessage"
     },
-    "message_received": {
-      "$ref": "#/$defs/MessageReceivedPayload"
+    "message_ended": {
+      "$ref": "#/$defs/MessageEndedPayload"
+    },
+    "message_queued": {
+      "$ref": "#/$defs/MessageQueuedPayload"
     },
     "message_requeued": {
       "$ref": "#/$defs/MessageRequeuedPayload"
     },
+    "message_started": {
+      "$ref": "#/$defs/MessageStartedPayload"
+    },
     "session_closed": {
       "$ref": "#/$defs/SessionClosedPayload"
-    },
-    "turn_ended": {
-      "$ref": "#/$defs/TurnEndedPayload"
-    },
-    "turn_queued": {
-      "$ref": "#/$defs/TurnQueuedPayload"
-    },
-    "turn_started": {
-      "$ref": "#/$defs/TurnStartedPayload"
     }
   },
   "required": [
     "environment_output",
     "environment_phase",
     "environment_ready",
-    "message_delivered",
-    "message_received",
+    "message",
+    "message_ended",
+    "message_queued",
     "message_requeued",
-    "session_closed",
-    "turn_ended",
-    "turn_queued",
-    "turn_started"
+    "message_started",
+    "session_closed"
   ],
   "title": "LifecyclePayloads",
   "type": "object"