BEEOS CLOUD / DEVELOPER REFERENCE

接收运行时方法（投递）

读取、续期、确认投递，追加结果，以及使用租约鉴权的 HTTP 数据面。

Cloud 把运行时方法调用（例如 session/prompt）作为投递排入队列。投递消费者在当前租约下读取它们，在你的处理函数运行期间保持其有效，并允许你确认或追加结果。追加操作不会被盲目重放：结果不确定时通过操作历史对账。

NodeRuntimeDeliveryPort

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.runtime_delivery_port

默认的投递端口：用当前租约凭据通过 HTTP 从 Cloud 读取运行时方法投递，负责认领生命周期，并通过 consume() 启动消费者。在 Python 中由 RuntimeDeliveryPort 承担同样的角色。

class NodeRuntimeDeliveryPort implements RuntimeDeliveryPort
new NodeRuntimeDeliveryPort(readonly origin: RuntimeDeliveryOriginPort, readonly authority: RuntimeDeliveryAuthorityPort)

TypeScript · 构造

参数	类型	必填	默认值	说明
`origin`	RuntimeDeliveryOriginPort	是		提供 Cloud 消息服务的 origin（协议与主机）。
`authority`	RuntimeDeliveryAuthorityPort	是		提供当前运行时租约；通常是适配为 `RuntimeDeliveryAuthorityPort` 的注册协调器。

Python · 构造

参数	类型	必填	默认值	说明
`service_origin`	`str \| Callable[[], str \| Awaitable[str]]`	是		Cloud 消息服务的 origin，或返回它的函数（同步或异步均可）。
`authority`	`Any`	是		提供当前运行时租约；通常是适配为 `RuntimeDeliveryAuthorityPort` 的注册协调器。
`http_client`	`httpx.AsyncClient \| None`	否	`None`	可选的、用于发送请求的 `httpx.AsyncClient`。
`scoped_delivery_key`	`str \| None`	否	`None`	作为 `X-Runtime-Delivery-Key` 发送的投递密钥；会话模型投影和定时任务投递需要它。

consume

创建读取、续期并分发投递的消费者。调用其 start() 开始；处理函数必须确认（acknowledge）每条投递。

consume(options: RuntimeDeliveryConsumeOptions): RuntimeDeliveryConsumer

TypeScript · 参数

参数	类型	必填	默认值	说明
`options`	RuntimeDeliveryConsumeOptions	是		消费者的处理函数、错误回调与调优参数。

返回值 RuntimeDeliveryConsumer

Python · 参数

参数	类型	必填	默认值	说明
`on_delivery`	`Callable[..., Any]`	是		收到每条 `RuntimeMethodDelivery` 时与消费者一起被调用，可以是同步或异步函数；处理完成后必须确认该投递。
`on_error`	`Callable[[BaseException], None] \| None`	否	`None`	读取、续期和处理环节的错误会传给它；未提供时这些错误被忽略。
`max_count`	`int`	否	`32`	单次读取最多返回的投递数量。
`block_ms`	`int`	否	`5000`	没有投递时，服务端最多挂起读取请求的时间，单位毫秒。
`idle_delay_s`	`float`	否	`0.5`	没有租约或读取结果无需处理时的停顿秒数，默认 0.5。
`renew_interval_s`	`float`	否	`20.0`	对处理中的投递进行续期的间隔秒数，默认 20。

返回值 RuntimeDeliveryConsumer

startConversationRun

仅 TypeScript

用当前租约发送会话运行的开始请求，返回原始 Response。已签名的操作准入由调用方负责。

async startConversationRun(input: ConversationRuntimeBoundaryStartRequest): Promise<Response>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	ConversationRuntimeBoundaryStartRequest	是		开始会话运行的已签名请求，其中的租约必须与当前租约一致。

返回值 Promise<Response>

finishConversationRun

仅 TypeScript

用当前租约发送会话运行的结束请求，返回原始 Response。

async finishConversationRun(input: ConversationRuntimeBoundaryFinishRequest): Promise<Response>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	ConversationRuntimeBoundaryFinishRequest	是		结束会话运行的已签名请求，其中的租约必须与当前租约一致。

返回值 Promise<Response>

current_lease

仅 Python

返回授权方提供的当前租约，没有则为 None。

def current_lease() -> Any

Python · 参数

无参数。

返回值 Any

read

仅 Python

最多读取 max_count 条投递，最长等待 block_ms 毫秒。应答无效时抛出 HarnessProtocolError。

async def read(*, max_count: int, block_ms: int) -> list[RuntimeMethodDelivery]

Python · 参数

参数	类型	必填	默认值	说明
`max_count`	`int`	是		单次读取最多返回的投递数量。
`block_ms`	`int`	是		没有投递时，服务端最多挂起读取请求的时间，单位毫秒。

返回值 list[RuntimeMethodDelivery]

renew

仅 Python

为给定投递续期并返回应答，其中 notPending 列出已不再待处理的投递。

async def renew(delivery_ids: list[str]) -> dict[str, Any]

Python · 参数

参数	类型	必填	默认值	说明
`delivery_ids`	`list[str]`	是		投递（delivery）的标识列表。

返回值 dict[str, Any]

acknowledge

仅 Python

确认这些投递，使其不再被重复投递。若应答确认的 ID 与给定的不完全一致，抛出 HarnessProtocolError。

async def acknowledge(delivery_ids: list[str]) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`delivery_ids`	`list[str]`	是		投递（delivery）的标识列表。

返回值 Any

history

仅 Python

返回操作已保存的历史：{"status": "not_found"}、{"status": "expired"} 或 {"status": "found", "snapshot": ...}。

async def history(operation_id: str) -> dict[str, Any]

Python · 参数

参数	类型	必填	默认值	说明
`operation_id`	`str`	是		操作的标识。

返回值 dict[str, Any]

append

仅 Python

向某个操作追加一条消息并返回应答。该调用不会自动重试，结果不确定时需用 history 对账。

async def append(operation_id: str, type: str, payload: Any, execution_grant: str | None = None) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`operation_id`	`str`	是		操作的标识。
`type`	`str`	是		追加消息的类型。
`payload`	`Any`	是		追加消息的载荷。
`execution_grant`	`str \| None`	否	`None`	随操作下发的执行授权，作为 `X-BeeOS-Execution-Grant` 发送。

返回值 Any

history_boundary

仅 Python

为某个会话执行历史边界动作。fields 使用 snake_case 名称，会被映射为线上字段名。

async def history_boundary(conversation_id: str, action: str, body: Mapping[str, Any] | None = None, **fields: Any) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`conversation_id`	`str`	是		会话的标识。
`action`	`str`	是		历史边界动作：`prepare`、`resetting`、`reset_done`、`commit`、`abort` 或 `reconcile`。
`body`	`Mapping[str, Any] \| None`	否	`None`	调用的请求体，为与 JSON 兼容的数据。
`**fields`	`Any`	是		额外的请求体字段：`operation_id`、`request_message_id`、`request_hash`、`boundary_token`、`effect_receipt`、`run_convergence` 或 `active_run_registration_id`。其他名称会抛出 `HarnessProtocolError`。

返回值 Any

project_session_model

仅 Python

发布某个会话的会话模型。需要 scoped_delivery_key；该调用可能被重试。

async def project_session_model(conversation_id: str, body: Any) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`conversation_id`	`str`	是		会话的标识。
`body`	`Any`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Any

deliver_cron

仅 Python

把定时任务的结果投递到某个会话。需要 scoped_delivery_key；该调用可能被重试。

async def deliver_cron(conversation_id: str, body: Any) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`conversation_id`	`str`	是		会话的标识。
`body`	`Any`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Any

RuntimeClaimClient

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.claims

调用认领生命周期的各接口：认领下一个或指定的操作、为认领续期、释放认领。

class RuntimeClaimClient
new RuntimeClaimClient(readonly http: RuntimeLeaseHttp)

TypeScript · 构造

参数	类型	必填	默认值	说明
`http`	RuntimeLeaseHttp	是		发送请求的、带租约鉴权的 HTTP 客户端。

Python · 构造

参数	类型	必填	默认值	说明
`http`	RuntimeLeaseHttp	是		发送请求的、带租约鉴权的 HTTP 客户端。

claimNext / claim_next

认领下一个待处理的操作。返回的 status 为 claimed、empty 或 fenced。

async claimNext(credential: RuntimeLeaseCredential, body: RuntimeClaimNextRequest): Promise<{ status: string }>

TypeScript · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	RuntimeClaimNextRequest	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Promise<{ status: string }>

Python · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	`dict[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 dict[str, Any]

claimExact / claim_exact

认领指定的某个操作。返回的 status 为 claimed、already_claimed、fenced、epoch_handoff_required 或 terminal。

async claimExact(credential: RuntimeLeaseCredential, body: RuntimeClaimExactRequest): Promise<{ status: string }>

TypeScript · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	RuntimeClaimExactRequest	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Promise<{ status: string }>

Python · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	`dict[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 dict[str, Any]

renewClaim / renew_claim

为认领续期。返回的 status 为 renewed、fenced、expired 或 terminal。

async renewClaim(credential: RuntimeLeaseCredential, body: RuntimeClaimRenewRequest): Promise<{ status: string }>

TypeScript · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	RuntimeClaimRenewRequest	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Promise<{ status: string }>

Python · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	`dict[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 dict[str, Any]

releaseClaim / release_claim

带原因释放认领。除非 Cloud 返回 204，否则抛出 HarnessProtocolError。

async releaseClaim(credential: RuntimeLeaseCredential, body: RuntimeClaimReleaseRequest): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	RuntimeClaimReleaseRequest	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Promise<void>

Python · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`body`	`dict[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 None

RuntimeDeliveryAuthorityPort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

为投递端口提供当前租约。把你的注册协调器适配成它即可。

interface RuntimeDeliveryAuthorityPort

currentLease

返回含凭据的当前租约；没有时返回 null。

currentLease(): RuntimeDeliveryAuthorityLease | null

TypeScript · 参数

无参数。

返回值 RuntimeDeliveryAuthorityLease | null

subscribeAuthority

可选。注册租约变化时被调用的监听器，使处理中的任务得以取消。返回用于移除监听器的函数。

subscribeAuthority?(listener: () => void): () => void

TypeScript · 参数

参数	类型	必填	默认值	说明
`listener`	`() => void`	是		租约变化时调用的回调。

返回值 () => void

RuntimeDeliveryConsumer

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.runtime_delivery_port

运行中的消费者：读取并续期投递、调用你的处理函数；处理函数通过下列方法读取操作历史、追加消息并确认投递。

interface RuntimeDeliveryConsumer

Python · 构造

参数	类型	必填	说明
`port`	RuntimeDeliveryPort	是	实际发出请求的投递端口。
`on_delivery`	`Callable[..., Any]`	是	收到每条 `RuntimeMethodDelivery` 时与消费者一起被调用，可以是同步或异步函数。
`on_error`	`Callable[[BaseException], None] \| None`	是	读取、续期和处理环节的错误会传给它。
`max_count`	`int`	是	单次读取最多返回的投递数量。
`block_ms`	`int`	是	没有投递时，服务端最多挂起读取请求的时间，单位毫秒。
`idle_delay_s`	`float`	是	没有租约或无事可处理时的停顿秒数。
`renew_interval_s`	`float`	是	对处理中的投递进行续期的间隔秒数。

start

启动读取与续期循环。运行期间再次调用不会产生效果。

start(): void

TypeScript · 参数

无参数。

返回值 void

Python · 参数

无参数。

返回值 None

stop

停止读取与续期，循环结束后完成。在 TypeScript 中，运行中的处理函数会通过其中止信号被取消。

stop(signal?: AbortSignal): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`signal`	`AbortSignal`	否		中止该信号会取消这次调用。

返回值 Promise<void>

Python · 参数

无参数。

返回值 None

history

用当前租约返回某个操作已保存的历史。没有有效租约时抛出错误。

history(operationId: string): Promise<RuntimeDeliveryHistory>

TypeScript · 参数

参数	类型	必填	默认值	说明
`operationId`	`string`	是		操作的标识。

返回值 Promise<RuntimeDeliveryHistory>

Python · 参数

参数	类型	必填	默认值	说明
`operation_id`	`str`	是		操作的标识。

返回值 dict[str, Any]

append

用当前租约向某个操作追加一条消息并返回回执。该调用不会自动重试；回执为 outcome_unknown 时，请用 history 对账。

append(operationId: string, type: string, payload: JsonValue, executionGrant?: string): Promise<RuntimeDeliveryAppendReceipt>

TypeScript · 参数

参数	类型	必填	说明
`operationId`	`string`	是	操作的标识。
`type`	`string`	是	追加消息的类型。
`payload`	JsonValue	是	追加消息的载荷。
`executionGrant`	`string`	否	随操作下发的执行授权，作为 `X-BeeOS-Execution-Grant` 发送。

返回值 Promise<RuntimeDeliveryAppendReceipt>

Python · 参数

参数	类型	必填	默认值	说明
`operation_id`	`str`	是		操作的标识。
`type`	`str`	是		追加消息的类型。
`payload`	`Any`	是		追加消息的载荷。
`execution_grant`	`str \| None`	否	`None`	随操作下发的执行授权，作为 `X-BeeOS-Execution-Grant` 发送。

返回值 Any

acknowledge

确认投递，使其不再被重复投递。处理函数完成后调用。

acknowledge(deliveryIds: readonly string[]): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`deliveryIds`	`readonly string[]`	是		投递（delivery）的标识列表。

返回值 Promise<void>

Python · 参数

参数	类型	必填	默认值	说明
`delivery_ids`	`list[str]`	是		投递（delivery）的标识列表。

返回值 Any

history_boundary

仅 Python

通过端口为某个会话执行历史边界动作。

async def history_boundary(conversation_id: str, action: str, body: Mapping[str, Any] | None = None, **fields: Any) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`conversation_id`	`str`	是		会话的标识。
`action`	`str`	是		历史边界动作：`prepare`、`resetting`、`reset_done`、`commit`、`abort` 或 `reconcile`。
`body`	`Mapping[str, Any] \| None`	否	`None`	调用的请求体，为与 JSON 兼容的数据。
`**fields`	`Any`	是		snake_case 形式的额外请求体字段，与 `RuntimeDeliveryPort.history_boundary` 接受的相同。

返回值 Any

RuntimeDeliveryOriginPort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

提供 Cloud 消息服务 origin 的来源。

interface RuntimeDeliveryOriginPort

serviceOrigin

解析消息服务的 origin（协议与主机）。

serviceOrigin(): Promise<string>

TypeScript · 参数

无参数。

返回值 Promise<string>

RuntimeDeliveryPort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

投递传输的入口：负责创建消费者。

interface RuntimeDeliveryPort

consume

创建消费者；调用其 start() 开始运行。

consume(options: RuntimeDeliveryConsumeOptions): RuntimeDeliveryConsumer

TypeScript · 参数

参数	类型	必填	默认值	说明
`options`	RuntimeDeliveryConsumeOptions	是		消费者的处理函数、错误回调与调优参数。

返回值 RuntimeDeliveryConsumer

RuntimeLeaseHttp

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.lease_http

面向 Cloud 数据面的 HTTP 客户端。它只向一个固定的 origin 附带租约凭据（Authorization: Bearer），并拒绝重定向和来自其他 origin 的应答。

class RuntimeLeaseHttp
new RuntimeLeaseHttp(readonly options: RuntimeLeaseHttpOptions)

TypeScript · 构造

参数	类型	必填	默认值	说明
`options`	RuntimeLeaseHttpOptions	是		`origin` 是唯一会收到凭据的 origin；`retry` 是默认重试策略（默认不重试）；`fetch` 用于替换全局 `fetch`。

Python · 构造

参数	类型	必填	默认值	说明
`origin`	`str`	是		凭据唯一允许发往的 origin，必须是不带用户信息的 `http` 或 `https`。
`client`	`httpx.AsyncClient \| None`	否	`None`	可选的 `httpx.AsyncClient`，用于发送请求；省略时使用临时客户端。
`timeout`	`float`	否	`30.0`	超时时间，单位秒。
`retry`	BackoffPolicy \| None	否	`None`	调用的默认重试策略；`None` 表示不自动重试。

属性

名称	类型	说明
`readonly origin`	`URL`	凭据所发往的固定 origin。

fetch

带租约凭据发送请求。retry: true 表示该调用幂等；默认从不重放，因此追加或确认结果不确定时由调用方对账。目标位于其他 origin 时抛出错误。

async fetch(target: string | URL, credential: RuntimeLeaseCredential, init: RequestInit = {}, resilience: { retry?: boolean | BackoffPolicy } = {}): Promise<Response>

TypeScript · 参数

参数	类型	必填	默认值	说明
`target`	`string \| URL`	是		以 `/` 开头的路径，或位于固定 origin 上的绝对 URL。
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`init`	`RequestInit`	否	`{}`	标准 `fetch` 选项（method、body、headers、signal）。
`resilience`	{ retry?: boolean \| BackoffPolicy }	否	`{}`	`retry`：`true` 表示使用 transient 策略，也可传 `BackoffPolicy`，`false` 表示不重试。会重试的状态码为 502、503、504。

返回值 Promise<Response>

Python · 参数

参数	类型	必填	默认值	说明
`method`	`str`	是		HTTP 方法。
`target`	`str`	是		以 `/` 开头的路径，或位于固定 origin 上的绝对 URL。
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`json_body`	`Any`	否	`None`	要发送的 JSON 请求体。
`content`	`bytes \| None`	否	`None`	作为请求体发送的原始字节。
`headers`	`Mapping[str, str] \| None`	否	`None`	额外的请求头。
`timeout`	`float \| None`	否	`None`	超时时间，单位秒。
`retry`	bool \| BackoffPolicy	否	`False`	`True` 表示使用 transient 策略，也可传 `BackoffPolicy`；`False`（默认）表示不重试。

返回值 httpx.Response

postJson

仅 TypeScript

发送 JSON POST 并返回原始 Response，由调用方自行映射业务错误。

async postJson(path: string, credential: RuntimeLeaseCredential, body: unknown, resilience?: { retry?: boolean | BackoffPolicy }, signal?: AbortSignal): Promise<Response>

TypeScript · 参数

参数	类型	必填	说明
`path`	`string`	是	请求路径。
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`resilience`	{ retry?: boolean \| BackoffPolicy }	否	与 `fetch` 相同的重试设置：`true`、`BackoffPolicy` 或 `false`。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<Response>

RuntimeMessagePlane

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.runtime_plane

面向同一个 Cloud 消息服务 origin 的调用：读取、续期、确认投递，读取操作历史，追加消息，以及执行会话级动作。

class RuntimeMessagePlane
new RuntimeMessagePlane(readonly http: RuntimeLeaseHttp)

TypeScript · 构造

参数	类型	必填	默认值	说明
`http`	RuntimeLeaseHttp	是		发送请求的、带租约鉴权的 HTTP 客户端。

Python · 构造

参数	类型	必填	默认值	说明
`http`	RuntimeLeaseHttp	是		发送请求的、带租约鉴权的 HTTP 客户端。

readDeliveries / read_deliveries

读取投递，请求最长挂起 blockMs 毫秒。返回解码后的应答。

async readDeliveries(credential: RuntimeLeaseCredential, input: { maxCount: number; blockMs: number }, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`input`	`{ maxCount: number; blockMs: number }`	是	`maxCount` 是最多返回的投递数；`blockMs` 是服务端最多等待投递的时长。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`max_count`	`int`	是	单次读取最多返回的投递数量。
`block_ms`	`int`	是	没有投递时，服务端最多挂起读取请求的时间，单位毫秒。

返回值 Any

renewDeliveries / renew_deliveries

为仍在处理的投递续期，返回解码后的应答。

async renewDeliveries(credential: RuntimeLeaseCredential, deliveryIds: readonly string[], signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`deliveryIds`	`readonly string[]`	是	投递（delivery）的标识列表。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`delivery_ids`	`list[str]`	是		投递（delivery）的标识列表。

返回值 Any

ackDeliveries / ack_deliveries

确认投递，返回解码后的应答。

async ackDeliveries(credential: RuntimeLeaseCredential, deliveryIds: readonly string[], signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`deliveryIds`	`readonly string[]`	是	投递（delivery）的标识列表。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`delivery_ids`	`list[str]`	是		投递（delivery）的标识列表。

返回值 Any

operationHistory / operation_history

获取某个操作已保存的历史。

async operationHistory(credential: RuntimeLeaseCredential, operationId: string, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operationId`	`string`	是	操作的标识。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	默认值	说明
`credential`	RuntimeLeaseCredential	是		为该调用授权的运行时租约凭据。
`operation_id`	`str`	是		操作的标识。

返回值 Any

appendOperationMessage / append_operation_message

向某个操作追加一条消息，不会自动重试。

async appendOperationMessage(credential: RuntimeLeaseCredential, operationId: string, body: { type: string; payload: unknown }, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operationId`	`string`	是	操作的标识。
`body`	`{ type: string; payload: unknown }`	是	调用的请求体，为与 JSON 兼容的数据。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operation_id`	`str`	是	操作的标识。
`type`	`str`	是	追加消息的类型。
`payload`	`Any`	是	追加消息的载荷。

返回值 Any

historyBoundary / history_boundary

为某个会话执行历史边界动作，该调用可能被重试。

async historyBoundary(credential: RuntimeLeaseCredential, conversationId: string, action: HistoryBoundaryAction, body: unknown, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`conversationId`	`string`	是	会话的标识。
`action`	HistoryBoundaryAction	是	历史边界动作：`prepare`、`resetting`、`reset_done`、`commit`、`abort` 或 `reconcile`。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`conversation_id`	`str`	是	会话的标识。
`action`	`str`	是	历史边界动作：`prepare`、`resetting`、`reset_done`、`commit`、`abort` 或 `reconcile`。
`body`	`Any`	是	调用的请求体，为与 JSON 兼容的数据。

返回值 Any

projectSessionModel / project_session_model

发布某个会话的会话模型。凭据必须带有 scopedDeliveryKey；该调用可能被重试。

async projectSessionModel(credential: RuntimeLeaseCredential, conversationId: string, body: unknown, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`conversationId`	`string`	是	会话的标识。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`conversation_id`	`str`	是	会话的标识。
`body`	`Any`	是	调用的请求体，为与 JSON 兼容的数据。

返回值 Any

deliverCron / deliver_cron

把定时任务的结果投递到某个会话。凭据必须带有 scopedDeliveryKey；该调用可能被重试。

async deliverCron(credential: RuntimeLeaseCredential, conversationId: string, body: unknown, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`conversationId`	`string`	是	会话的标识。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`conversation_id`	`str`	是	会话的标识。
`body`	`Any`	是	调用的请求体，为与 JSON 兼容的数据。

返回值 Any

RuntimeOperationFiles

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.runtime_plane

操作的文件调用：解析输入文件，以及预签名并确认输出文件。这些调用发往网关 origin，而不是消息服务。

class RuntimeOperationFiles
new RuntimeOperationFiles(readonly http: RuntimeLeaseHttp)

TypeScript · 构造

参数	类型	必填	默认值	说明
`http`	RuntimeLeaseHttp	是		发送请求的、带租约鉴权的 HTTP 客户端。

Python · 构造

参数	类型	必填	默认值	说明
`http`	RuntimeLeaseHttp	是		发送请求的、带租约鉴权的 HTTP 客户端。

resolveInput / resolve_input

把某个操作的输入文件解析为可下载的位置。该调用可能被重试。

async resolveInput(credential: RuntimeLeaseCredential, operationId: string, body: unknown, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operationId`	`string`	是	操作的标识。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operation_id`	`str`	是	操作的标识。
`body`	`Any`	是	调用的请求体，为与 JSON 兼容的数据。

返回值 Any

presignOutput / presign_output

为某个操作的输出文件申请预签名上传位置。该调用可能被重试。

async presignOutput(credential: RuntimeLeaseCredential, operationId: string, body: unknown, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operationId`	`string`	是	操作的标识。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operation_id`	`str`	是	操作的标识。
`body`	`Any`	是	调用的请求体，为与 JSON 兼容的数据。

返回值 Any

confirmOutput / confirm_output

确认某个操作的输出文件已上传。该调用可能被重试。

async confirmOutput(credential: RuntimeLeaseCredential, operationId: string, body: unknown, signal?: AbortSignal): Promise<unknown>

TypeScript · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operationId`	`string`	是	操作的标识。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`signal`	`AbortSignal`	否	中止该信号会取消这次调用。

返回值 Promise<unknown>

Python · 参数

参数	类型	必填	说明
`credential`	RuntimeLeaseCredential	是	为该调用授权的运行时租约凭据。
`operation_id`	`str`	是	操作的标识。
`body`	`Any`	是	调用的请求体，为与 JSON 兼容的数据。

返回值 Any

create_runtime_delivery_port

Python beeos_cloud_harness_sdk.runtime_delivery_port · 仅 Python

创建 RuntimeDeliveryPort。

def create_runtime_delivery_port(*, service_origin: str | Callable[[], str | Awaitable[str]], authority: Any, http_client: httpx.AsyncClient | None = None, scoped_delivery_key: str | None = None) -> RuntimeDeliveryPort

Python · 参数

参数	类型	必填	默认值	说明
`service_origin`	`str \| Callable[[], str \| Awaitable[str]]`	是		Cloud 消息服务的 origin，或返回它的函数（同步或异步均可）。
`authority`	`Any`	是		提供当前租约的对象，可通过 `current_lease()`、`currentLease()` 或属性提供。
`http_client`	`httpx.AsyncClient \| None`	否	`None`	可选的、用于发送请求的 `httpx.AsyncClient`。
`scoped_delivery_key`	`str \| None`	否	`None`	作为 `X-Runtime-Delivery-Key` 发送的投递密钥；会话模型投影和定时任务投递需要它。

返回值 RuntimeDeliveryPort

putPresignedUpload

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.runtime_plane

用 PUT 把字节上传到预签名 URL，不会发送租约凭据。

async function putPresignedUpload(input: { url: string; allowedOrigin: string; body: Uint8Array; method?: string; requiredHeaders?: Record<string, string>; signal?: AbortSignal; fetchImpl?: typeof fetch; }): Promise<Response>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	`{ url: string; allowedOrigin: string; body: Uint8Array; method?: string; requiredHeaders?: Record<string, string>; signal?: AbortSignal; fetchImpl?: typeof fetch; }`	是		`url` 与 `allowedOrigin`（上传必须发往该 https origin）、`body` 字节，以及可选的 `method`（默认 `PUT`）、`requiredHeaders`、`signal`、`fetchImpl`。

返回值 Promise<Response>

Python · 参数

参数	类型	必填	默认值	说明
`url`	`str`	是		预签名上传 URL，必须使用 https 且不含用户信息。
`allowed_origin`	`str`	是		上传唯一允许发往的 origin。
`body`	`bytes`	是		调用的请求体，为与 JSON 兼容的数据。
`method`	`str`	否	`'PUT'`	HTTP 方法。
`required_headers`	`Mapping[str, str] \| None`	否	`None`	预签名 URL 要求携带的请求头。
`client`	`httpx.AsyncClient \| None`	否	`None`	可选的 `httpx.AsyncClient`，用于发送请求；省略时使用临时客户端。

返回值 httpx.Response

CLOUD_GATEWAY_RUNTIME_ROUTES

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.lease_http

构造网关上带租约鉴权的文件路由的路径。

const CLOUD_GATEWAY_RUNTIME_ROUTES: Readonly<{ outputFiles: (operationId: string, stage: "presign" | "confirm") => string; inputFilesResolve: (operationId: string) => string; }>

条目

名称	类型	说明
`outputFiles`	`(operationId: string, stage: "presign" \| "confirm") => string`	用于预签名或确认某个操作输出文件的路径。
`inputFilesResolve`	`(operationId: string) => string`	用于解析某个操作输入文件的路径。

CLOUD_MESSAGE_ROUTES

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.lease_http

带租约鉴权的消息服务路由的路径；与 RuntimeLeaseHttp 配合使用。

const CLOUD_MESSAGE_ROUTES: Readonly<{ deliveriesRead: string; deliveriesRenew: string; deliveriesAck: string; conversations: string; operationHistory: (operationId: string) => string; operationMessages: (operationId: string) => string; historyBoundary: (conversationId: string, action: HistoryBoundaryAction) => string; metadataModel: (conversationId: string) => string; cronDelivery: (conversationId: string) => string; claimNext: string; claimExact: (operationId: string) => string; claimRenew: (operationId: string) => string; claimRelease: (operationId: string) => string; }>

条目

名称	类型	说明
`deliveriesRead`	`string`	读取投递的路径。
`deliveriesRenew`	`string`	为投递续期的路径。
`deliveriesAck`	`string`	确认投递的路径。
`conversations`	`string`	同步会话的路径。
`operationHistory`	`(operationId: string) => string`	读取某个操作历史的路径。
`operationMessages`	`(operationId: string) => string`	向某个操作追加消息的路径。
`historyBoundary`	(conversationId: string, action: HistoryBoundaryAction) => string	某个会话的历史边界动作的路径。
`metadataModel`	`(conversationId: string) => string`	发布某个会话的会话模型的路径。
`cronDelivery`	`(conversationId: string) => string`	把定时任务结果投递到某个会话的路径。
`claimNext`	`string`	认领下一个待处理操作的路径。
`claimExact`	`(operationId: string) => string`	认领指定操作的路径。
`claimRenew`	`(operationId: string) => string`	为某个操作的认领续期的路径。
`claimRelease`	`(operationId: string) => string`	释放某个操作认领的路径。

HarnessProtocolError

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.runtime_plane

Cloud 返回错误状态码或结构不符合预期的应答，或调用在发出之前就被拒绝（例如缺少投递密钥）时抛出。

class HarnessProtocolError extends Error
new HarnessProtocolError(message: string, readonly status?: number, readonly body?: string)

TypeScript · 构造

参数	类型	必填	说明
`message`	`string`	是	错误信息。
`status`	`number`	否	HTTP 状态码（错误来自应答时提供）。
`body`	`string`	否	调用的请求体，为与 JSON 兼容的数据。

Python · 构造

参数	类型	必填	默认值	说明
`message`	`str`	是		错误信息。
`status`	`int \| None`	否	`None`	HTTP 状态码（错误来自应答时提供）。
`body`	`str \| None`	否	`None`	调用的请求体，为与 JSON 兼容的数据。

属性

名称	类型	说明
`readonly status?`	`number`	HTTP 状态码（错误来自应答时提供）。
`readonly body?`	`string`	应答的正文文本（错误来自应答时提供）。

错误与异常

本模块定义的错误类型。每个方法的说明会写明它在什么情况下抛出哪种错误。

错误	语言	说明
HarnessProtocolError	TypeScript, Python	Cloud 返回错误状态码或结构不符合预期的应答，或调用在发出之前就被拒绝（例如缺少投递密钥）时抛出。

BeeOS Cloud返回文档首页