ellipsis-dev 0.45.0__tar.gz → 0.47.0__tar.gz

{ellipsis_dev-0.45.0 → ellipsis_dev-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ellipsis-dev
-Version: 0.45.0
+Version: 0.47.0
 Summary: Python SDK for the Ellipsis agents platform: every /v1 operation, sync and async.
 Project-URL: Homepage, https://www.ellipsis.dev
 Project-URL: Documentation, https://www.ellipsis.dev/docs/api

{ellipsis_dev-0.45.0 → ellipsis_dev-0.47.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ellipsis-dev"
-version = "0.45.0"
+version = "0.47.0"
 description = "Python SDK for the Ellipsis agents platform: every /v1 operation, sync and async."
 readme = "README.md"
 license = "MIT"

{ellipsis_dev-0.45.0 → ellipsis_dev-0.47.0}/src/ellipsis/_client.py

@@ -18,13 +18,13 @@ from . import models
 from ._pagination import AsyncPage, SyncPage
 from ._session_handle import AsyncSessionsSugar, SyncSessionsSugar
 from ._transport import (
-    DEFAULT_BASE_URL,
     DEFAULT_TIMEOUT_SECONDS,
     MAX_RETRIES,
     AsyncTransport,
     Transport,
     build_body,
     build_query,
+    new_idempotency_key,
 )
 
 
@@ -747,10 +747,13 @@ class _SyncAgents:
 
     def list(
         self,
+        *,
+        label: Union[List[str], None] = None,
+        annotation: Union[List[str], None] = None,
     ) -> models.AgentsListResponse:
         """List Agents
 
-        List agents.
+        List agents, optionally only those with the given labels and annotations.
 
         Required permissions: read:configs.
         API key: Supported.
@@ -760,8 +763,14 @@ class _SyncAgents:
         Grant match patterns can further restrict access to individual resources.
         """
         path = "/v1/agents"
+        query = build_query(
+            {
+                "label": label,
+                "annotation": annotation,
+            }
+        )
         response = self._transport.request(
-            "GET", path, response_model=models.AgentsListResponse
+            "GET", path, response_model=models.AgentsListResponse, query=query
         )
         assert response is not None
         return response
@@ -815,9 +824,10 @@ class _SyncAgents:
         environment: Union[str, models.EnvironmentConfig_Input, None] = None,
         force_rebuild: Union[bool, None] = None,
         gemini: Union[models.GeminiOverrides, None] = None,
+        idempotency_key: Union[str, None] = None,
         images: Union[List[models.ImageAttachment], None] = None,
         input: Union[dict[str, Any], None] = None,
-        metadata: Union[dict[str, Union[str, None]], None] = None,
+        metadata: Union[models.ConfigMetadataPatch, None] = None,
         output: Union[models.OutputConfig, None] = None,
         permissions: Union[models.PermissionsConfig_Input, None] = None,
         skills: Union[List[models.SkillRef_Input], None] = None,
@@ -854,6 +864,9 @@ class _SyncAgents:
             "environment": environment,
             "force_rebuild": force_rebuild,
             "gemini": gemini,
+            "idempotency_key": idempotency_key
+            if idempotency_key is not None
+            else new_idempotency_key(),
             "images": images,
             "input": input,
             "metadata": metadata,
@@ -1191,10 +1204,13 @@ class _SyncEnvironments:
 
     def list(
         self,
+        *,
+        label: Union[List[str], None] = None,
+        annotation: Union[List[str], None] = None,
     ) -> models.EnvironmentsListResponse:
         """List Environments
 
-        List saved environments.
+        List saved environments, optionally only those with the given labels and annotations.
 
         Required permissions: read:environments.
         API key: Supported.
@@ -1203,8 +1219,14 @@ class _SyncEnvironments:
         Higher permission levels include lower levels: read < write < delete.
         """
         path = "/v1/environments"
+        query = build_query(
+            {
+                "label": label,
+                "annotation": annotation,
+            }
+        )
         response = self._transport.request(
-            "GET", path, response_model=models.EnvironmentsListResponse
+            "GET", path, response_model=models.EnvironmentsListResponse, query=query
         )
         assert response is not None
         return response
@@ -1909,13 +1931,15 @@ class _SyncSessions(SyncSessionsSugar):
         author_id: Union[int, None] = None,
         repo: Union[str, None] = None,
         status: Union[List[models.SessionStatus], None] = None,
+        label: Union[List[str], None] = None,
+        annotation: Union[List[str], None] = None,
     ) -> SyncPage[models.Session, models.SessionsListResponse]:
         """List Sessions
 
         List cloud agent sessions, newest first.
 
         Optionally filtered by agent (id or name), source, service, handler, time
-        window, attributed author, repository, and status.
+        window, attributed author, repository, status, labels, and annotations.
 
         Required permissions: read:sessions.
         API key: Supported.
@@ -1939,6 +1963,8 @@ class _SyncSessions(SyncSessionsSugar):
                 "author_id": author_id,
                 "repo": repo,
                 "status": status,
+                "label": label,
+                "annotation": annotation,
             }
         )
         response = self._transport.request(
@@ -1961,6 +1987,8 @@ class _SyncSessions(SyncSessionsSugar):
                 author_id=author_id,
                 repo=repo,
                 status=status,
+                label=label,
+                annotation=annotation,
             ),
         )
 
@@ -2047,20 +2075,23 @@ class _SyncSessions(SyncSessionsSugar):
         Send a message to a session.
 
         409 for mention, non-interactive, closed, archived, and
-        out-of-budget sessions. Returns the created message; a retried send with the
+        out-of-budget sessions. 403 when a session token sends to its own
+        session. Returns the created message; a retried send with the
         same idempotency_key returns the original one. The message is
         answered once the session's status is `idle` or `closed`.
 
         Required permissions: write:sessions.
         API key: Supported.
         CLI user token: Supported.
-        Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
+        Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration. Never the token's own session.
         Higher permission levels include lower levels: read < write < delete.
         Grant match patterns can further restrict access to individual resources.
         """
         path = f"/v1/sessions/{_quote(id)}/messages"
         body_fields: dict[str, Any] = {
-            "idempotency_key": idempotency_key,
+            "idempotency_key": idempotency_key
+            if idempotency_key is not None
+            else new_idempotency_key(),
             "images": images,
             "message": message,
         }
@@ -2105,8 +2136,9 @@ class _SyncSessions(SyncSessionsSugar):
         environment: Union[str, models.EnvironmentConfig_Input, None] = None,
         force_rebuild: Union[bool, None] = None,
         gemini: Union[models.GeminiConfig_Input, None] = None,
+        idempotency_key: Union[str, None] = None,
         images: Union[List[models.ImageAttachment], None] = None,
-        metadata: Union[dict[str, str], None] = None,
+        metadata: Union[models.ConfigMetadata_Input, None] = None,
         output: Union[models.OutputConfig, None] = None,
         permissions: Union[models.PermissionsConfig_Input, None] = None,
         skills: Union[List[models.SkillRef_Input], None] = None,
@@ -2144,6 +2176,9 @@ class _SyncSessions(SyncSessionsSugar):
             "environment": environment,
             "force_rebuild": force_rebuild,
             "gemini": gemini,
+            "idempotency_key": idempotency_key
+            if idempotency_key is not None
+            else new_idempotency_key(),
             "images": images,
             "metadata": metadata,
             "output": output,
@@ -2254,9 +2289,9 @@ class _SyncSessions(SyncSessionsSugar):
         thread, pull request, issue, or Linear issue it answers starts a
         new session. A session is also archived when it closes and after
         the account's `archive_inactive_sessions_days` without a message.
-        When the account sets session log retention, the session's
-        records, messages, and prompt are deleted that many days after it
-        was archived (`archived.deletes_at`). The session itself stays.
+        The session's records, messages, and prompt are deleted the
+        account's `session_logs_days` after it was archived
+        (`archived.deletes_at`). The session itself stays.
 
         Set archived to false to clear both fields and let the session
         take messages again. 409 `session_superseded` when a newer session
@@ -2645,7 +2680,7 @@ class _SyncWebhooksDeliveries:
         List webhook deliveries, newest first.
 
         Includes verification pings and deliveries for deleted webhooks.
-        History is retained for 30 days. Retries belong to the same delivery.
+        History is kept for 7 days. Retries belong to the same delivery.
 
         Required permissions: read:webhooks.
         API key: Supported.
@@ -2740,7 +2775,7 @@ class _SyncWebhooks:
         Delete a webhook and cancel outstanding deliveries.
 
         An HTTP request already in flight may finish. Delivery history remains
-        available for 30 days. Deletion frees a webhook slot.
+        available for 7 days. Deletion frees a webhook slot.
 
         Required permissions: delete:webhooks.
         API key: Supported.
@@ -2864,7 +2899,7 @@ class Ellipsis:
         self,
         api_key: str,
         *,
-        base_url: str = DEFAULT_BASE_URL,
+        base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = MAX_RETRIES,
     ) -> None:
@@ -3639,10 +3674,13 @@ class _AsyncAgents:
 
     async def list(
         self,
+        *,
+        label: Union[List[str], None] = None,
+        annotation: Union[List[str], None] = None,
     ) -> models.AgentsListResponse:
         """List Agents
 
-        List agents.
+        List agents, optionally only those with the given labels and annotations.
 
         Required permissions: read:configs.
         API key: Supported.
@@ -3652,8 +3690,14 @@ class _AsyncAgents:
         Grant match patterns can further restrict access to individual resources.
         """
         path = "/v1/agents"
+        query = build_query(
+            {
+                "label": label,
+                "annotation": annotation,
+            }
+        )
         response = await self._transport.request(
-            "GET", path, response_model=models.AgentsListResponse
+            "GET", path, response_model=models.AgentsListResponse, query=query
         )
         assert response is not None
         return response
@@ -3707,9 +3751,10 @@ class _AsyncAgents:
         environment: Union[str, models.EnvironmentConfig_Input, None] = None,
         force_rebuild: Union[bool, None] = None,
         gemini: Union[models.GeminiOverrides, None] = None,
+        idempotency_key: Union[str, None] = None,
         images: Union[List[models.ImageAttachment], None] = None,
         input: Union[dict[str, Any], None] = None,
-        metadata: Union[dict[str, Union[str, None]], None] = None,
+        metadata: Union[models.ConfigMetadataPatch, None] = None,
         output: Union[models.OutputConfig, None] = None,
         permissions: Union[models.PermissionsConfig_Input, None] = None,
         skills: Union[List[models.SkillRef_Input], None] = None,
@@ -3746,6 +3791,9 @@ class _AsyncAgents:
             "environment": environment,
             "force_rebuild": force_rebuild,
             "gemini": gemini,
+            "idempotency_key": idempotency_key
+            if idempotency_key is not None
+            else new_idempotency_key(),
             "images": images,
             "input": input,
             "metadata": metadata,
@@ -4083,10 +4131,13 @@ class _AsyncEnvironments:
 
     async def list(
         self,
+        *,
+        label: Union[List[str], None] = None,
+        annotation: Union[List[str], None] = None,
     ) -> models.EnvironmentsListResponse:
         """List Environments
 
-        List saved environments.
+        List saved environments, optionally only those with the given labels and annotations.
 
         Required permissions: read:environments.
         API key: Supported.
@@ -4095,8 +4146,14 @@ class _AsyncEnvironments:
         Higher permission levels include lower levels: read < write < delete.
         """
         path = "/v1/environments"
+        query = build_query(
+            {
+                "label": label,
+                "annotation": annotation,
+            }
+        )
         response = await self._transport.request(
-            "GET", path, response_model=models.EnvironmentsListResponse
+            "GET", path, response_model=models.EnvironmentsListResponse, query=query
         )
         assert response is not None
         return response
@@ -4803,13 +4860,15 @@ class _AsyncSessions(AsyncSessionsSugar):
         author_id: Union[int, None] = None,
         repo: Union[str, None] = None,
         status: Union[List[models.SessionStatus], None] = None,
+        label: Union[List[str], None] = None,
+        annotation: Union[List[str], None] = None,
     ) -> AsyncPage[models.Session, models.SessionsListResponse]:
         """List Sessions
 
         List cloud agent sessions, newest first.
 
         Optionally filtered by agent (id or name), source, service, handler, time
-        window, attributed author, repository, and status.
+        window, attributed author, repository, status, labels, and annotations.
 
         Required permissions: read:sessions.
         API key: Supported.
@@ -4833,6 +4892,8 @@ class _AsyncSessions(AsyncSessionsSugar):
                 "author_id": author_id,
                 "repo": repo,
                 "status": status,
+                "label": label,
+                "annotation": annotation,
             }
         )
         response = await self._transport.request(
@@ -4855,6 +4916,8 @@ class _AsyncSessions(AsyncSessionsSugar):
                 author_id=author_id,
                 repo=repo,
                 status=status,
+                label=label,
+                annotation=annotation,
             ),
         )
 
@@ -4941,20 +5004,23 @@ class _AsyncSessions(AsyncSessionsSugar):
         Send a message to a session.
 
         409 for mention, non-interactive, closed, archived, and
-        out-of-budget sessions. Returns the created message; a retried send with the
+        out-of-budget sessions. 403 when a session token sends to its own
+        session. Returns the created message; a retried send with the
         same idempotency_key returns the original one. The message is
         answered once the session's status is `idle` or `closed`.
 
         Required permissions: write:sessions.
         API key: Supported.
         CLI user token: Supported.
-        Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
+        Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration. Never the token's own session.
         Higher permission levels include lower levels: read < write < delete.
         Grant match patterns can further restrict access to individual resources.
         """
         path = f"/v1/sessions/{_quote(id)}/messages"
         body_fields: dict[str, Any] = {
-            "idempotency_key": idempotency_key,
+            "idempotency_key": idempotency_key
+            if idempotency_key is not None
+            else new_idempotency_key(),
             "images": images,
             "message": message,
         }
@@ -4999,8 +5065,9 @@ class _AsyncSessions(AsyncSessionsSugar):
         environment: Union[str, models.EnvironmentConfig_Input, None] = None,
         force_rebuild: Union[bool, None] = None,
         gemini: Union[models.GeminiConfig_Input, None] = None,
+        idempotency_key: Union[str, None] = None,
         images: Union[List[models.ImageAttachment], None] = None,
-        metadata: Union[dict[str, str], None] = None,
+        metadata: Union[models.ConfigMetadata_Input, None] = None,
         output: Union[models.OutputConfig, None] = None,
         permissions: Union[models.PermissionsConfig_Input, None] = None,
         skills: Union[List[models.SkillRef_Input], None] = None,
@@ -5038,6 +5105,9 @@ class _AsyncSessions(AsyncSessionsSugar):
             "environment": environment,
             "force_rebuild": force_rebuild,
             "gemini": gemini,
+            "idempotency_key": idempotency_key
+            if idempotency_key is not None
+            else new_idempotency_key(),
             "images": images,
             "metadata": metadata,
             "output": output,
@@ -5148,9 +5218,9 @@ class _AsyncSessions(AsyncSessionsSugar):
         thread, pull request, issue, or Linear issue it answers starts a
         new session. A session is also archived when it closes and after
         the account's `archive_inactive_sessions_days` without a message.
-        When the account sets session log retention, the session's
-        records, messages, and prompt are deleted that many days after it
-        was archived (`archived.deletes_at`). The session itself stays.
+        The session's records, messages, and prompt are deleted the
+        account's `session_logs_days` after it was archived
+        (`archived.deletes_at`). The session itself stays.
 
         Set archived to false to clear both fields and let the session
         take messages again. 409 `session_superseded` when a newer session
@@ -5539,7 +5609,7 @@ class _AsyncWebhooksDeliveries:
         List webhook deliveries, newest first.
 
         Includes verification pings and deliveries for deleted webhooks.
-        History is retained for 30 days. Retries belong to the same delivery.
+        History is kept for 7 days. Retries belong to the same delivery.
 
         Required permissions: read:webhooks.
         API key: Supported.
@@ -5634,7 +5704,7 @@ class _AsyncWebhooks:
         Delete a webhook and cancel outstanding deliveries.
 
         An HTTP request already in flight may finish. Delivery history remains
-        available for 30 days. Deletion frees a webhook slot.
+        available for 7 days. Deletion frees a webhook slot.
 
         Required permissions: delete:webhooks.
         API key: Supported.
@@ -5758,7 +5828,7 @@ class AsyncEllipsis:
         self,
         api_key: str,
         *,
-        base_url: str = DEFAULT_BASE_URL,
+        base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = MAX_RETRIES,
     ) -> None:

{ellipsis_dev-0.45.0 → ellipsis_dev-0.47.0}/src/ellipsis/_stream.py

@@ -17,7 +17,7 @@ from urllib.parse import quote
 
 from . import frames
 from ._errors import EllipsisError
-from ._transport import DEFAULT_BASE_URL
+from ._transport import resolve_base_url
 
 WS_CLOSE_NORMAL = 1000
 WS_CLOSE_AUTH_FAILED = 1008
@@ -146,7 +146,7 @@ async def stream_session(
     session_id: str,
     api_key: str,
     on_frame: Callable[[frames.StreamFrame], None | Awaitable[None]],
-    base_url: str = DEFAULT_BASE_URL,
+    base_url: str | None = None,
     after_seq: int = 0,
     max_reconnects: int = DEFAULT_MAX_RECONNECTS,
 ) -> StreamOutcome:
@@ -164,6 +164,7 @@ async def stream_session(
             "the stream client needs the `websockets` package: pip install 'ellipsis-dev[stream]'"
         ) from exc
 
+    resolved_base_url = resolve_base_url(base_url)
     cursor = after_seq
     ever_received_frame = False
     attempt = 0
@@ -190,7 +191,7 @@ async def stream_session(
         failure = ""
         try:
             async with websockets.connect(
-                _ws_url(base_url, session_id, cursor),
+                _ws_url(resolved_base_url, session_id, cursor),
                 additional_headers={"Authorization": f"Bearer {api_key}"},
             ) as socket:
                 while True:

{ellipsis_dev-0.45.0 → ellipsis_dev-0.47.0}/src/ellipsis/_transport.py

@@ -5,8 +5,10 @@ calls `request()` with an operation's method/path/params/body and a response
 model; everything HTTP lives here.
 """
 
+import os
 import random
 import time
+import uuid
 from typing import Any, TypeVar
 
 import httpx
@@ -16,6 +18,9 @@ from pydantic_core import to_jsonable_python
 from ._errors import APIError, TransportError, api_error_for
 
 DEFAULT_BASE_URL = "https://api.ellipsis.dev"
+# Read when the caller passes no base_url. Session VMs set it, so code running
+# inside a session reaches the API without configuration.
+BASE_URL_ENV = "ELLIPSIS_API_BASE_URL"
 DEFAULT_TIMEOUT_SECONDS = 60.0
 # 429 and 5xx are retried with exponential backoff + jitter; everything else
 # raises immediately. Only idempotent-safe by the API's own semantics: every
@@ -56,6 +61,18 @@ def build_body(body: BaseModel) -> Any:
     return body.model_dump(mode="json", by_alias=True, exclude_none=True)
 
 
+def new_idempotency_key() -> str:
+    """A fresh key for a request that takes `idempotency_key`. The generated
+    client makes one per call when the caller sets none, so the transport's
+    retries of that call reuse it and the server applies the call once."""
+    return uuid.uuid4().hex
+
+
+def resolve_base_url(base_url: str | None) -> str:
+    """The explicit base URL, else ELLIPSIS_API_BASE_URL, else the default."""
+    return (base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL).rstrip("/")
+
+
 def _backoff_seconds(attempt: int, retry_after: str | None) -> float:
     if retry_after is not None:
         try:
@@ -72,13 +89,13 @@ class Transport:
         self,
         *,
         api_key: str,
-        base_url: str = DEFAULT_BASE_URL,
+        base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = MAX_RETRIES,
     ) -> None:
         self._max_retries = max_retries
         # Public so the stream client / sugar can reuse the credential.
-        self.base_url = base_url.rstrip("/")
+        self.base_url = resolve_base_url(base_url)
         self.api_key = api_key
         self._client = httpx.Client(
             base_url=self.base_url,
@@ -124,12 +141,12 @@ class AsyncTransport:
         self,
         *,
         api_key: str,
-        base_url: str = DEFAULT_BASE_URL,
+        base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = MAX_RETRIES,
     ) -> None:
         self._max_retries = max_retries
-        self.base_url = base_url.rstrip("/")
+        self.base_url = resolve_base_url(base_url)
         self.api_key = api_key
         self._client = httpx.AsyncClient(
             base_url=self.base_url,

{ellipsis_dev-0.45.0 → ellipsis_dev-0.47.0}/src/ellipsis/models.py

@@ -116,20 +116,14 @@ class BudgetCeiling(EllipsisModel):
 
 
 class DataRetentionSettings_Output(EllipsisModel):
-    api_requests_days: Union[int, None] = Field(
-        description="Reserved; API request retention is not yet enforced."
-    )
     archive_inactive_sessions_days: int = Field(
         description="Days without a message before a session is archived. A session is also archived when it closes. 1 to 90, default 7."
     )
     environment_snapshots_days: int = Field(
-        description="Retention of newly created reusable environment snapshots, up to 28 days from creation. Paused session workspaces have a separate lifetime."
-    )
-    session_logs_days: Union[int, None] = Field(
-        description="Days after a session is archived before its records and messages are deleted. The session itself stays. Null keeps them."
+        description="Retention of newly created reusable environment snapshots, up to 7 days from creation. Paused session workspaces have a separate lifetime."
     )
-    webhooks_days: Union[int, None] = Field(
-        description="Reserved; webhook retention is not yet enforced."
+    session_logs_days: int = Field(
+        description="Days after a session is archived before its records and messages are deleted. The session itself stays. 1 to 365, default 365."
     )
 
 
@@ -171,8 +165,12 @@ class AccountSettings(EllipsisModel):
 
 
 class ConfigMetadata_Output(EllipsisModel):
-    annotations: dict[str, str]
-    labels: list[str]
+    """Labels and annotations for your own use, the same block on an agent, an environment, and a session. They never change how anything runs."""
+
+    annotations: dict[str, str] = Field(
+        description="String key/value pairs to tag and filter by. A key contains no `:`."
+    )
+    labels: list[str] = Field(description="Names to tag and filter by.")
 
 
 class AgentIdentity_Output(EllipsisModel):
@@ -932,8 +930,8 @@ class SessionConfig_Output(EllipsisModel):
     gemini: Union[GeminiConfig_Output, None] = Field(
         description="Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini."
     )
-    metadata: dict[str, str] = Field(
-        description="Arbitrary string key/value metadata stored on every session."
+    metadata: ConfigMetadata_Output = Field(
+        description="Labels and annotations stored on every session."
     )
     output: Union[OutputConfig, None]
     permissions: PermissionsConfig_Output
@@ -1050,8 +1048,15 @@ class Agent(EllipsisModel):
 
 
 class ConfigMetadata_Input(EllipsisModel):
-    annotations: Union[dict[str, str], None] = None
-    labels: Union[list[str], None] = None
+    """Labels and annotations for your own use, the same block on an agent, an environment, and a session. They never change how anything runs."""
+
+    annotations: Union[dict[str, str], None] = Field(
+        default=None,
+        description="String key/value pairs to tag and filter by. A key contains no `:`.",
+    )
+    labels: Union[list[str], None] = Field(
+        default=None, description="Names to tag and filter by."
+    )
 
 
 class AgentIdentity_Input(EllipsisModel):
@@ -1692,9 +1697,8 @@ class SessionConfig_Input(EllipsisModel):
         default=None,
         description="Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini.",
     )
-    metadata: Union[dict[str, str], None] = Field(
-        default=None,
-        description="Arbitrary string key/value metadata stored on every session.",
+    metadata: Union[ConfigMetadata_Input, None] = Field(
+        default=None, description="Labels and annotations stored on every session."
     )
     output: Union[OutputConfig, None] = None
     permissions: Union[PermissionsConfig_Input, None] = None
@@ -3106,6 +3110,18 @@ class CodexSessionRecord(EllipsisRecord):
     tools: Union[list[str], None]
 
 
+class ConfigMetadataPatch(EllipsisModel):
+    """Metadata merged into an agent's for one session."""
+
+    annotations: Union[dict[str, Union[str, None]], None] = Field(
+        default=None,
+        description="Each key you send sets that key, a `null` value removes the agent's key, and keys you leave out keep the agent's values.",
+    )
+    labels: Union[list[str], None] = Field(
+        default=None, description="Labels added to the agent's."
+    )
+
+
 class CreateAgentRequest(EllipsisModel):
     """Parameters for creating an agent."""
 
@@ -3262,23 +3278,17 @@ class CreditPurchaseReceipt(EllipsisModel):
 
 
 class DataRetentionSettings_Input(EllipsisModel):
-    api_requests_days: Union[int, None] = Field(
-        default=None, description="Reserved; API request retention is not yet enforced."
-    )
     archive_inactive_sessions_days: Union[int, None] = Field(
         default=None,
         description="Days without a message before a session is archived. A session is also archived when it closes. 1 to 90, default 7.",
     )
     environment_snapshots_days: Union[int, None] = Field(
         default=None,
-        description="Retention of newly created reusable environment snapshots, up to 28 days from creation. Paused session workspaces have a separate lifetime.",
+        description="Retention of newly created reusable environment snapshots, up to 7 days from creation. Paused session workspaces have a separate lifetime.",
     )
     session_logs_days: Union[int, None] = Field(
         default=None,
-        description="Days after a session is archived before its records and messages are deleted. The session itself stays. Null keeps them.",
-    )
-    webhooks_days: Union[int, None] = Field(
-        default=None, description="Reserved; webhook retention is not yet enforced."
+        description="Days after a session is archived before its records and messages are deleted. The session itself stays. 1 to 365, default 365.",
     )
 
 
@@ -3976,7 +3986,7 @@ class IntegrationSessionConfig(EllipsisModel):
         default=None,
         description="Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini.",
     )
-    metadata: Union[dict[str, str], None] = None
+    metadata: Union[ConfigMetadata_Output, None] = None
     permissions: Union[PermissionsConfig_Output, None] = None
     skills: Union[list[SkillRef_Output], None] = None
 
@@ -5373,7 +5383,7 @@ class SendSessionMessageRequest(EllipsisModel):
 
     idempotency_key: Union[str, None] = Field(
         default=None,
-        description="Optional retry-safety key, unique per (session, key): a retry with the same key returns the original message — no duplicate message, no double turn, no double spend. The SDK auto-generates one per send.",
+        description="Optional retry safety key, unique per session. A retry with the same key returns the original message, with no second message, turn, or spend. The SDKs make a key for each call that sets none, so their own retries never send a message twice.",
     )
     images: Union[list[ImageAttachment], None] = Field(
         default=None,
@@ -5425,7 +5435,7 @@ class SessionArchived(EllipsisModel):
         description="The GitHub user who archived the session; null if unknown or unavailable."
     )
     deletes_at: Union[datetime, None] = Field(
-        description="When the session's records and messages are deleted, from the account's current session log retention. It moves when the retention changes. Null when the account keeps them or they're already deleted."
+        description="When the session's records and messages are deleted, from the account's current session log retention. It moves when the retention changes. Null when they're already deleted."
     )
 
 
@@ -5727,8 +5737,8 @@ class Session(EllipsisModel):
         description="The saved handler and its effective display name when this session started, frozen at creation. Null for built-in responders, legacy sessions, and sessions started without a handler."
     )
     id: str = Field(description="Unique identifier of the session.")
-    metadata: dict[str, str] = Field(
-        description="Caller-supplied metadata key-value pairs."
+    metadata: ConfigMetadata_Output = Field(
+        description="Labels and annotations set when the session started."
     )
     output: Union[SessionOutput, None] = Field(
         description="The session's structured output: the `json_schema` the agent must satisfy and, once the agent has submitted it, the `result`."
@@ -5938,8 +5948,9 @@ class StartAgentSessionRequest(EllipsisModel):
     """Start a session from a saved agent. The body takes the fields of POST
     /v1/sessions, all optional, plus `input`. The session starts from the
     agent's `session` settings: each field you send replaces the agent's value for that field,
-    and each field you leave out keeps it. `metadata` is the exception: it is
-    merged into the agent's key by key, and a `null` value removes a key.
+    and each field you leave out keeps it. `metadata` is the exception: its
+    labels are added to the agent's, its annotations merge key by key, and a
+    `null` annotation value removes a key.
     Other lists and maps, and `environment`, are replaced whole, and naming the
     other harness replaces the agent's harness. `input` is required when the
     agent declares `input.json_schema` and rejected when it doesn't. Extra keys
@@ -5974,6 +5985,10 @@ class StartAgentSessionRequest(EllipsisModel):
         default=None,
         description="Gemini CLI options for this session. Sent fields replace the agent's; naming Gemini CLI on an agent that runs another harness replaces its harness and requires a model. Set at most one of claude_code, codex, or gemini.",
     )
+    idempotency_key: Union[str, None] = Field(
+        default=None,
+        description="Optional retry safety key, unique per account across POST /v1/sessions and POST /v1/agents/{id}/sessions. A retry with the same key returns the session the first request started instead of starting another. Only a request that started a session holds its key. A key is kept for 90 days. The SDKs make a key for each call that sets none, so their own retries never start a second session.",
+    )
     images: Union[list[ImageAttachment], None] = Field(
         default=None,
         description="Images attached to the first message, base64 inline. Requires the model's `images` capability, listed by `/v1/account/models`. Each becomes an `[Image #N]` placeholder in the prompt and an image block the model sees with it. Up to 10, 5 MiB each; PNG, JPEG, GIF, or WebP.",
@@ -5982,9 +5997,9 @@ class StartAgentSessionRequest(EllipsisModel):
         default=None,
         description="The typed payload for an agent that declares input.json_schema. Required when the agent declares a schema; rejected when it does not. Validated against the schema and rendered through input.message, or as formatted JSON if no template is set, and added after the prompt. The rendered message must be non-empty.",
     )
-    metadata: Union[dict[str, Union[str, None]], None] = Field(
+    metadata: Union[ConfigMetadataPatch, None] = Field(
         default=None,
-        description="Metadata merged into the agent's for this session. Each key you send sets that key, a `null` value removes the agent's key, and keys you leave out keep the agent's values.",
+        description="Metadata merged into the agent's for this session. Labels you send are added to the agent's. Each annotation key you send sets that key, a `null` value removes the agent's key, and keys you leave out keep the agent's values.",
     )
     output: Union[OutputConfig, None] = Field(
         default=None,
@@ -6062,13 +6077,17 @@ class StartSessionRequest(EllipsisModel):
         default=None,
         description="Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini.",
     )
+    idempotency_key: Union[str, None] = Field(
+        default=None,
+        description="Optional retry safety key, unique per account across POST /v1/sessions and POST /v1/agents/{id}/sessions. A retry with the same key returns the session the first request started instead of starting another. Only a request that started a session holds its key. A key is kept for 90 days. The SDKs make a key for each call that sets none, so their own retries never start a second session.",
+    )
     images: Union[list[ImageAttachment], None] = Field(
         default=None,
         description="Images attached to the first message, base64 inline. Requires the model's `images` capability, listed by `/v1/account/models`. Each becomes an `[Image #N]` placeholder in the prompt and an image block the model sees with it. Up to 10, 5 MiB each; PNG, JPEG, GIF, or WebP.",
     )
-    metadata: Union[dict[str, str], None] = Field(
+    metadata: Union[ConfigMetadata_Input, None] = Field(
         default=None,
-        description="Arbitrary string key/value metadata stored on the session.",
+        description="Labels and annotations stored on the session, to filter sessions by.",
     )
     output: Union[OutputConfig, None] = Field(
         default=None,
@@ -6466,6 +6485,7 @@ __all__ = [
     "ConfigManagedBy",
     "ConfigMetadata_Input",
     "ConfigMetadata_Output",
+    "ConfigMetadataPatch",
     "ConfigSpendWindow",
     "ConfigUsageBucket",
     "Cost",