chore: sync from ark-apis a103b7cd7b

VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkruntime"
-version = "0.8.0"
+version = "0.9.0"
 description = "Ark runtime SDK for Python"
 readme = "README.md"
 requires-python = ">=3.8"

src/arkruntime/types/session/__init__.py

@@ -12,9 +12,17 @@
 from .base64_document_source import Base64DocumentSource
 from .base64_image_source import Base64ImageSource
 from .cache_creation import CacheCreation
+from .checkpoint_component import CheckpointComponent
+from .checkpoint_component_status import CheckpointComponentStatus
+from .checkpoint_restore_config import CheckpointRestoreConfig
+from .checkpoint_session_snapshot import CheckpointSessionSnapshot
+from .checkpoint_status import CheckpointStatus
+from .create_session_checkpoint_request import CreateSessionCheckpointRequest
+from .create_session_checkpoint_response import CreateSessionCheckpointResponse
 from .create_session_request import CreateSessionRequest
 from .create_session_resource_request import CreateSessionResourceRequest
 from .create_session_upgrade_request import CreateSessionUpgradeRequest
+from .delete_session_checkpoint_response import DeleteSessionCheckpointResponse
 from .delete_session_response import DeleteSessionResponse
 from .document_source import DocumentSource
 from .environment_config_override import EnvironmentConfigOverride
@@ -25,7 +33,9 @@
 from .environment_with_upgrades import EnvironmentWithUpgrades
 from .file_document_source import FileDocumentSource
 from .file_image_source import FileImageSource
+from .get_session_checkpoint_response import GetSessionCheckpointResponse
 from .image_source import ImageSource
+from .list_session_checkpoints_response import ListSessionCheckpointsResponse
 from .list_session_events_response_wire import ListSessionEventsResponseWire
 from .list_session_resources_response import ListSessionResourcesResponse
 from .list_session_threads_response import ListSessionThreadsResponse
@@ -76,12 +86,14 @@
 )
 from .model_overrides import ModelOverrides
 from .model_upgrades import ModelUpgrades
+from .override_token_limits import OverrideTokenLimits
 from .plain_text_document_source import PlainTextDocumentSource
 from .search_result_citations import SearchResultCitations
 from .search_result_content import SearchResultContent
 from .send_session_events_request import SendSessionEventsRequest
 from .send_session_events_response import SendSessionEventsResponse
 from .session import Session
+from .session_checkpoint import SessionCheckpoint
 from .session_resource import SessionResource
 from .session_resource_access import SessionResourceAccess
 from .session_resource_type import SessionResourceType
@@ -102,9 +114,17 @@
     "Base64DocumentSource",
     "Base64ImageSource",
     "CacheCreation",
+    "CheckpointComponent",
+    "CheckpointComponentStatus",
+    "CheckpointRestoreConfig",
+    "CheckpointSessionSnapshot",
+    "CheckpointStatus",
+    "CreateSessionCheckpointRequest",
+    "CreateSessionCheckpointResponse",
     "CreateSessionRequest",
     "CreateSessionResourceRequest",
     "CreateSessionUpgradeRequest",
+    "DeleteSessionCheckpointResponse",
     "DeleteSessionResponse",
     "DocumentSource",
     "EnvironmentConfigOverride",
@@ -115,7 +135,9 @@
     "EnvironmentWithUpgrades",
     "FileDocumentSource",
     "FileImageSource",
+    "GetSessionCheckpointResponse",
     "ImageSource",
+    "ListSessionCheckpointsResponse",
     "ListSessionEventsResponseWire",
     "ListSessionResourcesResponse",
     "ListSessionThreadsResponse",
@@ -150,12 +172,14 @@
     "ManagedAgentsUserToolResultEventParams",
     "ModelOverrides",
     "ModelUpgrades",
+    "OverrideTokenLimits",
     "PlainTextDocumentSource",
     "SearchResultCitations",
     "SearchResultContent",
     "SendSessionEventsRequest",
     "SendSessionEventsResponse",
     "Session",
+    "SessionCheckpoint",
     "SessionResource",
     "SessionResourceAccess",
     "SessionResourceType",

src/arkruntime/types/session/checkpoint_component.py

@@ -0,0 +1,50 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Optional
+
+from arkruntime._models import BaseModel
+
+from .checkpoint_component_status import CheckpointComponentStatus
+
+
+class CheckpointComponent(BaseModel):
+    """
+    Checkpoint 中单个资源组件的脱敏执行摘要。
+
+    不暴露运行时 Snapshot ID、平台 TOS Prefix、Credential 等内部信息。
+    """
+
+    type: str
+    """
+    组件类型。
+    """
+    status: CheckpointComponentStatus
+    """
+    组件快照状态。
+    """
+    source_resource_id: Optional[str] = None
+    """
+    源资源 ID。
+    """
+    object_count: Optional[int] = None
+    """
+    快照对象数。
+    """
+    storage_bytes: Optional[int] = None
+    """
+    快照占用字节数。
+    """
+    error_code: Optional[str] = None
+    """
+    失败错误码。
+    """
+    error_message: Optional[str] = None
+    """
+    失败错误信息。
+    """

src/arkruntime/types/session/checkpoint_component_status.py

@@ -0,0 +1,20 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CheckpointComponentStatus(str, Enum):
+    """
+    单个 Checkpoint 组件（资源快照分区）的状态。
+    """
+
+    creating = "creating"
+    ready = "ready"
+    failed = "failed"
+    deleted = "deleted"

src/arkruntime/types/session/checkpoint_restore_config.py

@@ -0,0 +1,33 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+
+class CheckpointRestoreConfig(BaseModel):
+    """
+    跨账号 Checkpoint 恢复的目标账号侧配置。
+
+    是否提供分三种情况：
+    - 同账号恢复：**必须省略**，携带返回 400；
+    - 跨账号恢复但 Checkpoint 不含 customer TOS 数据（仅平台托管的
+    uploads/outputs/memory 等）：**必须省略**，携带返回 400，错误码
+    消息为 "checkpoint_restore_config is only allowed when the
+    checkpoint contains customer TOS data"；
+    - 跨账号恢复且 Checkpoint 包含 customer TOS 数据：**必填**
+    `tos_bucket`，声明调用方已离线同步好快照的目标账号 TOS 桶；
+    省略返回 400。
+
+    快照源 prefix、region、mount_path、access 均从 Checkpoint 继承，
+    最终 Session 目标 key 由平台生成。
+    """
+
+    tos_bucket: str
+    """
+    调用方已将 customer TOS 快照同步到的目标账号 TOS 桶。
+    """

src/arkruntime/types/session/checkpoint_session_snapshot.py

@@ -0,0 +1,49 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from arkruntime._models import BaseModel
+
+from .session_resource import SessionResource
+from .tag import Tag
+
+
+class CheckpointSessionSnapshot(BaseModel):
+    """
+    创建 Checkpoint 时冻结的用户可见 Session 配置。
+
+    `agent` / `environment` 反映创建瞬间的 wire 形态（分别与 Ark.Agent 的
+    Agent、Ark.Environment 的 Environment 同 shape），为保持本模块自足，
+    此处承载为 `Record<unknown>`。
+    """
+
+    agent: Optional[Dict[str, object]] = None
+    """
+    冻结的 Agent 快照。
+    """
+    environment: Optional[Dict[str, object]] = None
+    """
+    冻结的 Environment 快照。
+    """
+    resources: Optional[List[SessionResource]] = None
+    """
+    冻结的挂载资源列表。
+    """
+    vault_ids: Optional[List[str]] = None
+    """
+    冻结的可访问 Vault ID 列表。
+    """
+    title: Optional[str] = None
+    """
+    冻结的会话标题。
+    """
+    tags: Optional[List[Tag]] = None
+    """
+    冻结的资源标签。
+    """

src/arkruntime/types/session/checkpoint_status.py

@@ -0,0 +1,21 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CheckpointStatus(str, Enum):
+    """
+    Checkpoint 生命周期状态。
+    """
+
+    creating = "creating"
+    ready = "ready"
+    failed = "failed"
+    deleting = "deleting"
+    deleted = "deleted"

src/arkruntime/types/session/create_session_checkpoint_request.py

@@ -0,0 +1,21 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+
+class CreateSessionCheckpointRequest(BaseModel):
+    """
+    创建 Session Checkpoint 的请求体。
+    """
+
+    name: str
+    """
+    Checkpoint 名称；由调用方提供，长度 1–128，仅用于展示。
+    Checkpoint ID 由平台生成并在响应的 `id` 字段返回。
+    """

src/arkruntime/types/session/create_session_checkpoint_response.py

@@ -0,0 +1,22 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+from .session_checkpoint import SessionCheckpoint
+
+
+class CreateSessionCheckpointResponse(BaseModel):
+    """
+    `POST /sessions/{session_id}/checkpoints` 响应体。
+    """
+
+    checkpoint: SessionCheckpoint
+    """
+    创建出的 Checkpoint。
+    """

src/arkruntime/types/session/create_session_request.py

@@ -11,6 +11,7 @@
 from arkruntime._models import BaseModel
 
 from .agent_identifier import AgentIdentifier
+from .checkpoint_restore_config import CheckpointRestoreConfig
 from .environment_with_overrides import EnvironmentWithOverrides
 from .session_resource import SessionResource
 from .tag import Tag
@@ -25,13 +26,21 @@ class CreateSessionRequest(BaseModel):
     - AgentRef 对象：`{"type":"agent","id":"agent_...","version":1}`
     """
 
-    agent: AgentIdentifier
+    agent: Optional[AgentIdentifier] = None
     """
-    Agent 标识。
+    Agent 标识。普通创建必填；携带 `checkpoint_id` 恢复时可省略。
+
+    注意两种恢复基线的区别：
+    - **省略 `agent`**：完整继承 Checkpoint 冻结的 Agent 快照（含其
+    system / tools / model 接入配置等全部字段）；
+    - **显式提供 `agent`**：不是在 Checkpoint 快照上做局部修改，而是按
+    Agent 引用重新解析（指定 `version` 取该版本，省略取当前最新版；
+    源 Agent 在 Checkpoint 冻结后更新过就会拿到新配置），再在该基线
+    上应用 `agent_with_overrides` 覆写。
     """
     environment_id: Optional[str] = None
     """
-    关联的 Environment ID。与 `environment` 二选一。
+    关联的 Environment ID。与 `environment` 二选一；恢复时省略则继承快照。
     """
     environment: Optional[EnvironmentWithOverrides] = None
     """
@@ -43,13 +52,28 @@ class CreateSessionRequest(BaseModel):
     """
     resources: Optional[List[SessionResource]] = None
     """
-    挂载资源列表。
+    挂载资源列表。普通创建可指定；基于 Checkpoint 恢复时**必须省略**
+    （同账号 / 跨账号都完整继承 Checkpoint 资源，显式传空数组也返回 400）。
     """
     title: Optional[str] = None
     """
     会话人类可读标题。
     """
     vault_ids: Optional[List[str]] = None
     """
-    会话可访问的 Vault ID 列表。
+    会话可访问的 Vault ID 列表。基于 Checkpoint 同账号恢复时必须省略并
+    继承快照；跨账号恢复允许显式提供完整替换列表（空数组同样属于覆盖）。
+    """
+    checkpoint_id: Optional[str] = None
+    """
+    Session Checkpoint ID。省略时为普通创建；传入时以 ready 状态
+    Checkpoint 的冻结配置为默认值创建新 Session，未显式提供的字段均从
+    快照继承。Checkpoint 不存在 / 非 ready 返回对应 4xx。
+    """
+    checkpoint_restore_config: Optional[CheckpointRestoreConfig] = None
+    """
+    跨账号 customer TOS 恢复配置。**不是所有跨账号恢复都需要**：仅当跨
+    账号恢复且 Checkpoint 含 customer TOS 数据时必填；同账号恢复、以及
+    跨账号但不含 customer TOS 时必须省略，否则返回 400。三分支细则见
+    `CheckpointRestoreConfig`。
     """