@ellipsis-dev/sdk 0.5.0 → 0.7.0

package/schema/frames.schema.json

@@ -97,6 +97,7 @@
       "type": "string"
     },
     "AgentSessionWire": {
+      "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": {
         "agent_config_id": {
           "anyOf": [
@@ -108,6 +109,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the saved agent config the session ran on, if any.",
           "title": "Agent Config Id"
         },
         "attributed_user": {
@@ -119,7 +121,8 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "The GitHub user the session is attributed to, when the attribution is a GitHub user."
         },
         "attribution_id": {
           "anyOf": [
@@ -131,6 +134,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the principal the session is attributed to.",
           "title": "Attribution Id"
         },
         "attribution_type": {
@@ -142,7 +146,8 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Kind of principal the session is attributed to (e.g. a GitHub user or an API key)."
         },
         "client_version": {
           "anyOf": [
@@ -154,6 +159,7 @@
             }
           ],
           "default": null,
+          "description": "Version of the client that started the session, if reported.",
           "title": "Client Version"
         },
         "config_override": {
@@ -167,6 +173,7 @@
             }
           ],
           "default": null,
+          "description": "The partial-config diff applied for this run; null when the config was unmodified.",
           "title": "Config Override"
         },
         "context_repository": {
@@ -179,33 +186,40 @@
             }
           ],
           "default": null,
+          "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"
         },
         "created_at": {
+          "description": "When the session was created.",
           "format": "date-time",
           "title": "Created At",
           "type": "string"
         },
         "customer_id": {
+          "description": "Identifier of the account that owns the session.",
           "title": "Customer Id",
           "type": "string"
         },
@@ -218,7 +232,8 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "How the session's config was resolved from the account's defaults, when no explicit config was given."
         },
         "exit_status": {
           "anyOf": [
@@ -229,12 +244,15 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "How the session ended; null until it is terminal."
         },
         "harness": {
-          "$ref": "#/$defs/Harness"
+          "$ref": "#/$defs/Harness",
+          "description": "The coding-agent harness the session runs on."
         },
         "id": {
+          "description": "Unique identifier of the session.",
           "title": "Id",
           "type": "string"
         },
@@ -249,6 +267,7 @@
             }
           ],
           "default": null,
+          "description": "When the session last showed activity.",
           "title": "Last Activity At"
         },
         "last_message_at": {
@@ -262,6 +281,7 @@
             }
           ],
           "default": null,
+          "description": "When the session last received a message.",
           "title": "Last Message At"
         },
         "live_summary": {
@@ -274,6 +294,7 @@
             }
           ],
           "default": null,
+          "description": "A live summary of the session's progress while it runs.",
           "title": "Live Summary"
         },
         "metadata": {
@@ -281,6 +302,7 @@
             "type": "string"
           },
           "default": {},
+          "description": "Caller-supplied metadata key-value pairs.",
           "title": "Metadata",
           "type": "object"
         },
@@ -297,6 +319,7 @@
             }
           ],
           "default": null,
+          "description": "Pull requests the session created or updated.",
           "title": "Output Prs"
         },
         "parent_agent_session_id": {
@@ -309,6 +332,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the parent session that spawned this one, if any.",
           "title": "Parent Agent Session Id"
         },
         "parent_kind": {
@@ -320,7 +344,8 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "How this session relates to its parent session, if any."
         },
         "prompt": {
           "anyOf": [
@@ -332,10 +357,12 @@
             }
           ],
           "default": null,
+          "description": "The per-session prompt the session was started with.",
           "title": "Prompt"
         },
         "prompting": {
-          "$ref": "#/$defs/SessionPrompting"
+          "$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": [
@@ -347,14 +374,17 @@
             }
           ],
           "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"
+          "$ref": "#/$defs/BudgetSource",
+          "description": "Where the resolved budget came from."
         },
         "sandbox_id": {
           "anyOf": [
@@ -366,6 +396,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the sandbox the session runs in, if any.",
           "title": "Sandbox Id"
         },
         "session_key": {
@@ -378,6 +409,7 @@
             }
           ],
           "default": null,
+          "description": "Key identifying the durable conversation this session belongs to, or null for single-shot sessions.",
           "title": "Session Key"
         },
         "session_state": {
@@ -389,13 +421,16 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Lifecycle state of the durable conversation, or null for sessions without one."
         },
         "source": {
-          "$ref": "#/$defs/AgentSessionSource"
+          "$ref": "#/$defs/AgentSessionSource",
+          "description": "Where the session came from (e.g. react, manual, api, cli, mention, cron, laptop)."
         },
         "status": {
-          "$ref": "#/$defs/AgentSessionStatus"
+          "$ref": "#/$defs/AgentSessionStatus",
+          "description": "Execution status of the session."
         },
         "status_reason": {
           "anyOf": [
@@ -407,6 +442,7 @@
             }
           ],
           "default": null,
+          "description": "Human-readable reason for the current status, when there is one.",
           "title": "Status Reason"
         },
         "stopped_at": {
@@ -420,6 +456,7 @@
             }
           ],
           "default": null,
+          "description": "When a stop was requested, if one was.",
           "title": "Stopped At"
         },
         "stopped_by": {
@@ -432,6 +469,7 @@
             }
           ],
           "default": null,
+          "description": "GitHub account id of the user who stopped the session, if known.",
           "title": "Stopped By"
         },
         "stopped_by_user": {
@@ -443,7 +481,8 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "The GitHub user who stopped the session, if it was stopped."
         },
         "surface": {
           "anyOf": [
@@ -454,38 +493,46 @@
               "type": "null"
             }
           ],
-          "default": null
+          "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"
         },
         "updated_at": {
+          "description": "When the session was last updated.",
           "format": "date-time",
           "title": "Updated At",
           "type": "string"
@@ -500,6 +547,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the webhook event that triggered the session, if any.",
           "title": "Webhook Id"
         },
         "webhook_type": {
@@ -511,7 +559,8 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Type of the webhook event that triggered the session, if any."
         }
       },
       "required": [
@@ -578,7 +627,7 @@
       "type": "string"
     },
     "BudgetSource": {
-      "description": "Which layer actually determined the enforced budget.\n\nNot derivable from the run row alone (the run does not store the config\ncents or the customer default), so we persist it for the UI / audit.",
+      "description": "Which layer actually determined the enforced budget.\n\nNot derivable from the run row alone (the run does not store the config\ncents or the account default), so we persist it for the UI / audit.",
       "enum": [
         "system",
         "account",
@@ -599,7 +648,7 @@
       "type": "string"
     },
     "DeltaFrame": {
-      "description": "Fire-and-forget partial assistant output for the current response.\nNo seq, never resumable; superseded by the committed record.",
+      "description": "Fire-and-forget partial assistant output for the current response.\nCarries no sequence number and is never resumable; superseded by the\ncommitted record.",
       "properties": {
         "agent_turn_id": {
           "anyOf": [
@@ -611,6 +660,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the turn the delta belongs to, if known.",
           "title": "Agent Turn Id"
         },
         "kind": {
@@ -627,6 +677,7 @@
             }
           ],
           "default": null,
+          "description": "Output tokens generated so far for the current response.",
           "title": "Output Tokens"
         },
         "text": {
@@ -639,6 +690,7 @@
             }
           ],
           "default": null,
+          "description": "The partial output text.",
           "title": "Text"
         },
         "type": {
@@ -659,7 +711,7 @@
       "type": "object"
     },
     "DoneFrame": {
-      "description": "Terminal marker: the conversation is over, after the final session frame\ncarried the end state. Followed by close 1000.",
+      "description": "Terminal marker: the conversation is over, after the final session\nframe carried the end state. Followed by a normal close (1000).",
       "properties": {
         "type": {
           "const": "done",
@@ -675,9 +727,10 @@
       "type": "object"
     },
     "ErrorFrame": {
-      "description": "Terminal error marker, before close 1011. Curated copy only.",
+      "description": "Terminal error marker, sent before the server closes with code 1011.",
       "properties": {
         "message": {
+          "description": "A human-readable error message.",
           "title": "Message",
           "type": "string"
         },
@@ -735,15 +788,17 @@
     },
     "Harness": {
       "enum": [
-        "claude_code"
+        "claude_code",
+        "codex"
       ],
       "title": "Harness",
       "type": "string"
     },
     "HeartbeatFrame": {
-      "description": "Sent after HEARTBEAT_SECONDS of idleness; doubles as the dead-socket\nprobe.",
+      "description": "A keepalive sent after a period of idleness; doubles as the dead-socket\nprobe. Clients should treat roughly twice the heartbeat interval of\nsilence as a dead connection.",
       "properties": {
         "ts": {
+          "description": "Server time when the heartbeat was sent.",
           "format": "date-time",
           "title": "Ts",
           "type": "string"
@@ -778,6 +833,7 @@
         "mention_surface",
         "ephemeral_trigger",
         "non_interactive",
+        "harness_single_turn",
         "closed",
         "laptop"
       ],
@@ -785,9 +841,10 @@
       "type": "string"
     },
     "RecordsAppendFrame": {
-      "description": "Cursored append-only: raw records ordered by feed_seq, all sources.\nEvery record in the frame advances the resume cursor \u2014 including ones a\nclient renders as nothing (\u00a73.4).",
+      "description": "Cursored append-only delivery of session records, ordered by feed_seq,\nfrom all sources. Every record in the frame advances the resume cursor \u2014\nincluding ones a client renders as nothing.",
       "properties": {
         "records": {
+          "description": "New session records, ordered by feed_seq.",
           "items": {
             "$ref": "#/$defs/SessionRecordWire"
           },
@@ -825,10 +882,11 @@
       "type": "string"
     },
     "SessionFrame": {
-      "description": "LWW snapshot of the enriched public session (\u00a74.1) \u2014 the only way\nstatus/state/cost arrive. Resent whole on any field change.",
+      "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": {
         "session": {
-          "$ref": "#/$defs/AgentSessionWire"
+          "$ref": "#/$defs/AgentSessionWire",
+          "description": "The session's current state."
         },
         "type": {
           "const": "session",
@@ -863,9 +921,10 @@
       "type": "string"
     },
     "SessionMessageWire": {
-      "description": "The wire shape of one inbox message (\u00a73.3): what a queued chip renders\nand retires on. `author` is the message's attribution string; the webhook\nprovenance internals stay off the wire.",
+      "description": "One message in a session's inbox: what a queued message renders and\nretires on. The webhook provenance internals stay off the wire.",
       "properties": {
         "agent_session_id": {
+          "description": "Identifier of the session the message belongs to.",
           "title": "Agent Session Id",
           "type": "string"
         },
@@ -879,13 +938,16 @@
             }
           ],
           "default": null,
+          "description": "Display attribution of the message's sender.",
           "title": "Author"
         },
         "body": {
+          "description": "The message text.",
           "title": "Body",
           "type": "string"
         },
         "created_at": {
+          "description": "When the message was created.",
           "format": "date-time",
           "title": "Created At",
           "type": "string"
@@ -901,6 +963,7 @@
             }
           ],
           "default": null,
+          "description": "When the message was delivered to the agent, if it has been.",
           "title": "Delivered At"
         },
         "delivered_turn_id": {
@@ -913,6 +976,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the turn the message was delivered into, if any.",
           "title": "Delivered Turn Id"
         },
         "feed_seq": {
@@ -925,9 +989,11 @@
             }
           ],
           "default": null,
+          "description": "Where the message sits in the session's feed \u2014 placement metadata only, NOT a resume cursor (only records_append frames advance the cursor). Null for older rows.",
           "title": "Feed Seq"
         },
         "id": {
+          "description": "Unique identifier of the message.",
           "title": "Id",
           "type": "string"
         },
@@ -941,6 +1007,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the principal that sent the message, if attributed.",
           "title": "Sender Attribution Id"
         },
         "sender_attribution_type": {
@@ -952,10 +1019,12 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Kind of principal that sent the message, if attributed."
         },
         "status": {
-          "$ref": "#/$defs/SessionMessageStatus"
+          "$ref": "#/$defs/SessionMessageStatus",
+          "description": "Delivery status of the message."
         }
       },
       "required": [
@@ -1027,9 +1096,10 @@
       "type": "object"
     },
     "SessionRecordWire": {
-      "description": "The wire shape of one session record (\u00a73.3): the \u00a73.6 stable envelope +\nthe native `payload`, by explicit allowlist. Internal-only columns\n(`search_text`, `clis`, ingest bookkeeping, attribution denormalizations)\nare deliberately absent so internal model evolution stays free.",
+      "description": "One entry of a session's log: a stable envelope around the harness's\nnative payload. Internal-only columns are deliberately absent so internal\nmodel evolution stays free.",
       "properties": {
         "agent_session_id": {
+          "description": "Identifier of the session the record belongs to.",
           "title": "Agent Session Id",
           "type": "string"
         },
@@ -1043,6 +1113,7 @@
             }
           ],
           "default": null,
+          "description": "Identifier of the turn the record belongs to, if any.",
           "title": "Agent Turn Id"
         },
         "cost": {
@@ -1055,9 +1126,11 @@
             }
           ],
           "default": null,
+          "description": "Cost attributed to this record, if any.",
           "title": "Cost"
         },
         "created_at": {
+          "description": "When the record was created.",
           "format": "date-time",
           "title": "Created At",
           "type": "string"
@@ -1072,13 +1145,16 @@
             }
           ],
           "default": null,
+          "description": "Duration attributed to this record, if any.",
           "title": "Duration"
         },
         "feed_seq": {
+          "description": "The record's position in the session's ordered feed \u2014 the resume cursor for the stream and the records endpoints.",
           "title": "Feed Seq",
           "type": "integer"
         },
         "id": {
+          "description": "Unique identifier of the record.",
           "title": "Id",
           "type": "string"
         },
@@ -1092,18 +1168,22 @@
             }
           ],
           "default": null,
+          "description": "The model that produced this record, if any.",
           "title": "Model"
         },
         "payload": {
           "additionalProperties": true,
+          "description": "The harness's native line, verbatim. Consumers parse it at their own risk, versioned via record_format.",
           "title": "Payload",
           "type": "object"
         },
         "record_format": {
+          "description": "Versions the payload shape, e.g. claude_stream_json@2.0 or ellipsis_lifecycle@1.",
           "title": "Record Format",
           "type": "string"
         },
         "record_type": {
+          "description": "The record's type within its format.",
           "title": "Record Type",
           "type": "string"
         },
@@ -1117,6 +1197,7 @@
             }
           ],
           "default": null,
+          "description": "Correlates a user-echo record back to the session message it echoes, so clients can retire queued messages by id.",
           "title": "Session Message Id"
         },
         "source": {
@@ -1124,6 +1205,7 @@
           "type": "string"
         },
         "stream_seq": {
+          "description": "The record's position within its execution's stream.",
           "title": "Stream Seq",
           "type": "integer"
         },
@@ -1136,7 +1218,8 @@
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Token usage reported for this record, if any."
         },
         "tools": {
           "anyOf": [
@@ -1151,6 +1234,7 @@
             }
           ],
           "default": null,
+          "description": "Names of the tools used in this record, if any.",
           "title": "Tools"
         }
       },
@@ -1229,7 +1313,7 @@
       "type": "object"
     },
     "SnapshotFrame": {
-      "description": "First frame after accept. Lean: session + open inbox only \u2014 records\nalways arrive via records_append (\u00a73.4).",
+      "description": "The first frame after the stream connects: the session plus its open\ninbox. Records always arrive separately via records_append frames.",
       "properties": {
         "earliest_feed_seq": {
           "anyOf": [
@@ -1240,9 +1324,11 @@
               "type": "null"
             }
           ],
+          "description": "The retention head: the lowest feed_seq still stored for this session, or null when it has no stored records. A client resuming from after_seq < earliest_feed_seq - 1 knows history is truncated.",
           "title": "Earliest Feed Seq"
         },
         "messages": {
+          "description": "The session's open (pending) inbox messages.",
           "items": {
             "$ref": "#/$defs/SessionMessageWire"
           },
@@ -1251,11 +1337,13 @@
         },
         "protocol": {
           "default": 3,
+          "description": "Echoes the protocol version the server is serving.",
           "title": "Protocol",
           "type": "integer"
         },
         "session": {
-          "$ref": "#/$defs/AgentSessionWire"
+          "$ref": "#/$defs/AgentSessionWire",
+          "description": "The session's current state."
         },
         "type": {
           "const": "snapshot",
@@ -1343,7 +1431,7 @@
     }
   },
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "description": "One server-to-client frame of the Ellipsis session stream protocol v3 (WS /v1/sessions/{id}/stream?protocol=3). Clients MUST ignore frames with unknown `type` values \u2014 additive frames are not a protocol break.",
+  "description": "One server-to-client frame of the Ellipsis session stream protocol v3 (WS /sessions/{id}/stream?protocol=3). Clients MUST ignore frames with unknown `type` values \u2014 additive frames are not a protocol break.",
   "oneOf": [
     {
       "$ref": "#/$defs/SnapshotFrame"