BEEOS CLOUD / DEVELOPER REFERENCE

注册与租约

注册运行时、用心跳续租，并持久化运行时身份。

harness 先向 Cloud 注册并获得短期的运行时租约。租约凭证授权之后所有数据面调用，因此协调器用带签名的心跳保持租约有效，并在租约丢失时通知你。注册与心跳请求都带有用你持有的 Ed25519 密钥签出的身份证明。

InstanceAuthorityRuntimeRegistrationTransport

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

现成的 RuntimeRegistrationTransport：通过 AgentGatewayClient 发送注册与心跳请求。每个请求只发送一次（重试由协调器负责），会校验应答，并把注册冲突转换为对应的带类型注册错误。

class InstanceAuthorityRuntimeRegistrationTransport implements RuntimeRegistrationTransport
new InstanceAuthorityRuntimeRegistrationTransport(readonly options: { gateway: AgentGatewayClient; registrationId: string })

TypeScript · 构造

参数	类型	必填	默认值	说明
`options`	{ gateway: AgentGatewayClient; registrationId: string }	是		`gateway` 是带签名的 Agent Gateway 客户端；`registrationId` 是发送心跳所属的注册 ID。

register

发送注册请求并返回授权方的应答。

async register(request: RuntimeRegistrationRequest): Promise<RuntimeRegistrationResult>

TypeScript · 参数

参数	类型	必填	默认值	说明
`request`	RuntimeRegistrationRequest	是		带身份证明的已签名注册请求。

返回值 Promise<RuntimeRegistrationResult>

heartbeat

为该注册发送心跳并返回授权方的应答。

async heartbeat(request: RuntimeHeartbeatRequest): Promise<RuntimeHeartbeatResult>

TypeScript · 参数

参数	类型	必填	默认值	说明
`request`	RuntimeHeartbeatRequest	是		带身份证明的已签名心跳请求。

返回值 Promise<RuntimeHeartbeatResult>

RuntimeRegistrationAuthoritySource

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

当前租约及其变化的只读视图。数据面组件借此跟随租约，而不必持有协调器。

interface RuntimeRegistrationAuthoritySource

属性

名称	类型	说明
`readonly authorityLease`	RuntimeRegistrationAuthorityLease \| null	当前租约及处理方身份；没有有效租约时为 `null`。

subscribeAuthority

注册监听器；租约变化时以新租约调用，租约丢失时以 null 调用。返回用于移除监听器的函数。

subscribeAuthority(listener: (lease: RuntimeRegistrationAuthorityLease | null) => void): () => void

TypeScript · 参数

参数	类型	必填	默认值	说明
`listener`	(lease: RuntimeRegistrationAuthorityLease \| null) => void	是		接收新租约（或 `null`）的回调。

返回值 () => void

RuntimeRegistrationCoordinator

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

负责运行时注册与心跳循环。租约一旦丢失，会产生变更的认领必须立即停止。

class RuntimeRegistrationCoordinator
new RuntimeRegistrationCoordinator(readonly transport: RuntimeRegistrationTransport, readonly config: RuntimeRegistrationConfig, readonly onLeaseLost: (reason: "fenced" | "expired" | "heartbeat_failed", cause?: unknown) => void, readonly now: () => number = Date.now)

TypeScript · 构造

参数	类型	必填	默认值	说明
`transport`	RuntimeRegistrationTransport	是		负责发送注册与心跳请求。
`config`	RuntimeRegistrationConfig	是		注册意图、身份与恢复设置。
`onLeaseLost`	`(reason: "fenced" \| "expired" \| "heartbeat_failed", cause?: unknown) => void`	是		租约丢失时调用。`reason` 为 `fenced`、`expired` 或 `heartbeat_failed`；有底层错误时由 `cause` 携带。
`now`	`() => number`	否	`Date.now`	毫秒时钟，测试时可替换，默认 `Date.now`。

属性

名称	类型	说明
`readonly lease`	RuntimeActiveLease \| null / RuntimeActiveLease \| None	当前有效租约；尚未获得或按时钟已过期时为 `null`。
`readonly canClaimMutations`	`boolean`	存在有效租约时为 `true`；一旦变为 `false`，就必须立刻停止会产生变更的认领。
`readonly authorityLease`	RuntimeRegistrationAuthorityLease \| null	当前租约加处理方身份（不可变对象），或 `null`。不要记录或持久化：其中含租约凭据。
`transport`	RuntimeRegistrationTransport	发送注册与心跳请求的对象。
`keys`	AgentKeyPair	用其私钥签署身份证明的密钥对。
`identity`	RuntimeRegistrationIdentity	持久的注册身份：注册 ID、处理方身份、日志存储 ID 与日志代数。
`target_instance_id`	`str`	该 harness 必须注册到的 Cloud 实例。租约属于其他实例时视为被隔离（fenced）。
`runtime_methods`	`tuple[str, ...]`	该 harness 实际处理、并在注册中声明的运行时方法。SDK 无法推断它们。
`capabilities`	`tuple[str, ...]`	该 harness 实际提供、并在注册中声明的能力。
`contract_revision`	`str`	注册时声明的运行时契约版本，默认 `RUNTIME_RPC_CONTRACT_REVISION`。
`manifest_digest`	`str`	注册时声明的运行时方法清单摘要，默认 `RUNTIME_CURRENT_MANIFEST_DIGEST`。
`identity_store_path`	`Path \| None`	协调器推进日志代数或注册谱系后，用来保存身份的文件。为 `None` 时变更只保留在内存中。
`fenced_retry`	BackoffPolicy	收到 `fenced` 应答后重新注册所用的退避策略。默认 `FENCED_RETRY`：30 秒起步、翻倍至 5 分钟，不限次数。
`heartbeat_failure_threshold`	`int`	连续出现多少次可重试的心跳传输失败后才丢弃租约，默认 3。
`now`	`Any`	返回带时区 `datetime` 的时钟，测试时可替换，默认取当前 UTC 时间。
`active`	RuntimeActiveLease \| None	最近一次成功注册或心跳得到的租约，或 `None`。它可能已过期；需要校验过的值请用 `lease`。
`lease_ready`	`asyncio.Event`	存在有效租约时被置位、租约丢失或协调器停止时被清除的 `asyncio.Event`。请等待它，而不是轮询。
`errors`	`dict[str, str]`	各阶段最近一次的错误文本，键为 `register` 与 `heartbeat`；该阶段成功后对应条目被移除。
`is_active`	`bool`	存在有效且未过期的租约时为 `True`。

subscribeAuthority

仅 TypeScript

注册监听器；租约变化时以新的授权租约调用，租约丢失时以 null 调用。返回用于移除监听器的函数。

subscribeAuthority(listener: (lease: RuntimeRegistrationAuthorityLease | null) => void): () => void

TypeScript · 参数

参数	类型	必填	默认值	说明
`listener`	(lease: RuntimeRegistrationAuthorityLease \| null) => void	是		接收新授权租约（或 `null`）的回调。

返回值 () => void

start

注册运行时并启动心跳循环。返回租约；若注册没有立即成功则返回 null，随后按应答在后台继续重试。

async start(): Promise<RuntimeActiveLease | null>

TypeScript · 参数

无参数。

返回值 Promise<RuntimeActiveLease | null>

Python · 参数

无参数。

返回值 RuntimeActiveLease | None

stop

停止所有定时器、丢弃租约并通知租约监听器。仍在途的请求的应答会被忽略。

stop(): void

TypeScript · 参数

无参数。

返回值 void

Python · 参数

无参数。

返回值 None

wait_until_active

仅 Python

等待到存在可用租约并返回它；超时则返回当前租约（可能为 None）。

async def wait_until_active(timeout: float | None = None) -> RuntimeActiveLease | None

Python · 参数

参数	类型	必填	默认值	说明
`timeout`	`float \| None`	否	`None`	最长等待秒数；`None` 表示不限时间。

返回值 RuntimeActiveLease | None

RuntimeRegistrationTransport

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

负责发送注册与心跳请求。想改变请求到达 Cloud 的方式时实现它。

interface RuntimeRegistrationTransport

register

仅 TypeScript

发送注册请求并返回授权方的应答。

register(request: RuntimeRegistrationRequest): Promise<RuntimeRegistrationResult>

TypeScript · 参数

参数	类型	必填	默认值	说明
`request`	RuntimeRegistrationRequest	是		已签名的注册请求。

返回值 Promise<RuntimeRegistrationResult>

heartbeat

仅 TypeScript

发送心跳并返回授权方的应答。

heartbeat(request: RuntimeHeartbeatRequest): Promise<RuntimeHeartbeatResult>

TypeScript · 参数

参数	类型	必填	默认值	说明
`request`	RuntimeHeartbeatRequest	是		已签名的心跳请求。

返回值 Promise<RuntimeHeartbeatResult>

register_runtime

仅 Python

以给定 JSON 请求体发送 POST /api/v1/runtime/registrations，返回解码后的 JSON 应答。

async def register_runtime(body: Mapping[str, Any]) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`body`	`Mapping[str, Any]`	是		注册请求的 JSON 请求体。

返回值 Any

heartbeat_runtime

仅 Python

以给定 JSON 请求体发送 POST /api/v1/runtime/registrations/{registrationId}/heartbeat，返回解码后的 JSON 应答。

async def heartbeat_runtime(registration_id: str, body: Mapping[str, Any]) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`registration_id`	`str`	是		要发送心跳的注册 ID。
`body`	`Mapping[str, Any]`	是		心跳请求的 JSON 请求体。

返回值 Any

RuntimeTransportFailurePolicy

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

统计连续的可重试传输失败，并在达到阈值时给出信号，避免一次网关抖动就丢弃租约或认领。

class RuntimeTransportFailurePolicy
new RuntimeTransportFailurePolicy(readonly threshold = 3)

TypeScript · 构造

参数	类型	必填	默认值	说明
`threshold`	`number`	否	`3`	触发该策略所需的连续失败次数，默认 3。

recordSuccess

收到任何权威（非传输层）应答后，把失败计数清零。

recordSuccess(): void

TypeScript · 参数

无参数。

返回值 void

recordFailure

记录一次传输失败。仍在容忍范围内时返回 false，租约或认领保持有效；达到阈值时返回 true 并重置计数，调用方此时必须把租约或认领视为丢失。

recordFailure(): boolean

TypeScript · 参数

无参数。

返回值 boolean

classifyRuntimeRegistrationConflict

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

解析注册请求 409 应答的正文，返回对应的带类型错误：等待交接、推进日志代数，或需要所有者重置。

function classifyRuntimeRegistrationConflict(detail: string): RuntimeRegistrationHandoffRequiredError | RuntimeRegistrationJournalAdvanceRequiredError | RuntimeRegistrationOwnerResetRequiredError

TypeScript · 参数

参数	类型	必填	默认值	说明
`detail`	`string`	是		注册请求 409 应答的正文文本。

返回值 RuntimeRegistrationHandoffRequiredError | RuntimeRegistrationJournalAdvanceRequiredError | RuntimeRegistrationOwnerResetRequiredError

Python · 参数

参数	类型	必填	默认值	说明
`detail`	`str`	是		注册请求 409 应答的正文文本。

返回值 RuntimeRegistrationHandoffRequired | RuntimeRegistrationJournalAdvanceRequired | RuntimeRegistrationOwnerResetRequired | RuntimeRegistrationIntentConflict | None

load_or_create_identity

Python beeos_cloud_harness_sdk.registration · 仅 Python

从 path 加载注册身份，或创建并保存新身份。保存的处理方身份与请求的不同时，会新建注册 ID 并把日志代数加一。

def load_or_create_identity(path: Path, *, handler_identity: str) -> RuntimeRegistrationIdentity

Python · 参数

参数	类型	必填	默认值	说明
`path`	`Path`	是		身份文件；缺失的父目录会被创建。
`handler_identity`	`str`	是		本处理进程的身份，例如其 Pod 或容器名。

返回值 RuntimeRegistrationIdentity

save_identity

Python beeos_cloud_harness_sdk.registration · 仅 Python

通过临时文件加原子重命名把身份写成 JSON，文件权限为 0600。

def save_identity(path: Path, identity: RuntimeRegistrationIdentity) -> None

Python · 参数

参数	类型	必填	默认值	说明
`path`	`Path`	是		身份文件；缺失的父目录会被创建。
`identity`	RuntimeRegistrationIdentity	是		要持久化的身份。

返回值 None

FENCED_RETRY

Python beeos_cloud_harness_sdk.registration · 仅 Python

收到可恢复的 fenced 应答后的退避策略：30 秒起步、翻倍至 5 分钟，不限次数。

FENCED_RETRY = BackoffPolicy(float('inf'), 30000, 300000, 2)

HEARTBEAT_TRANSPORT_FAILURE_THRESHOLD

Python beeos_cloud_harness_sdk.registration · 仅 Python

在把租约视为丢失之前，允许连续出现的心跳传输失败次数。

HEARTBEAT_TRANSPORT_FAILURE_THRESHOLD = 3

IDENTITY_FILE_NAME

Python beeos_cloud_harness_sdk.registration · 仅 Python

保存注册身份时约定使用的文件名 runtime-registration-identity.json。

IDENTITY_FILE_NAME = 'runtime-registration-identity.json'

RUNTIME_CURRENT_MANIFEST_DIGEST

Python beeos_cloud_harness_sdk.registration · 仅 Python

与本 SDK 版本的契约版本相匹配的运行时方法清单摘要。

RUNTIME_CURRENT_MANIFEST_DIGEST = 'd5db2c5e7c78cee73e5672a3c18a8e56179b28888f6fbb660d98ec021ca9de9b'

RUNTIME_RPC_CONTRACT_REVISION

Python beeos_cloud_harness_sdk.registration · 仅 Python

本 SDK 版本实现的运行时契约版本，随注册一起发送。

RUNTIME_RPC_CONTRACT_REVISION = '2026-07-14.3'

RUNTIME_RPC_PROTOCOL_VERSION

Python beeos_cloud_harness_sdk.registration · 仅 Python

运行时 RPC 协议的版本，当前为 1。

RUNTIME_RPC_PROTOCOL_VERSION = 1

RuntimeRegistrationError

Python beeos_cloud_harness_sdk.registration · 仅 Python

描述注册结果的各错误的基类。

class RuntimeRegistrationError(RuntimeError)

RuntimeRegistrationHandoffRequiredError

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

上一个租约仍占有该实例。等它过期后，再次注册同一注册意图。

class RuntimeRegistrationHandoffRequiredError extends Error
new RuntimeRegistrationHandoffRequiredError(retryAfterMs = 65_000)

TypeScript · 构造

参数	类型	必填	默认值	说明
`retryAfterMs`	`number`	否	`65_000`	重新注册前的等待时间，单位毫秒，默认 65000。

Python · 构造

参数	类型	必填	默认值	说明
`retry_after_ms`	`int`	否	`65000`	重新注册前的等待时间，单位毫秒，默认 65000。

属性

名称	类型	说明
`readonly retryAfterMs`	`number`	重新注册前的等待时间，单位毫秒。

RuntimeRegistrationIntentConflict

Python beeos_cloud_harness_sdk.registration · 仅 Python

已保存的注册 ID 与正在发送的注册意图不再一致，例如运行时方法列表发生了变化。协调器随后会新建注册 ID 并推进日志代数。

class RuntimeRegistrationIntentConflict(RuntimeRegistrationError)
def __init__() -> None

RuntimeRegistrationJournalAdvanceRequiredError

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

上一个租约已过期，下一次注册必须使用下一代日志代数。重试前把持久身份精确推进一次；不要把它当作交接等待。

class RuntimeRegistrationJournalAdvanceRequiredError extends Error
new RuntimeRegistrationJournalAdvanceRequiredError(detail?: { currentJournalGeneration?: `${bigint}`; expectedJournalGeneration?: `${bigint}`; })

TypeScript · 构造

参数	类型	必填	默认值	说明
`detail`	{ currentJournalGeneration?: `${bigint}`; expectedJournalGeneration?: `${bigint}`; }	否		从冲突正文解析出的可选代数：当前日志代数与期望的下一代数。

Python · 构造

参数	类型	必填	默认值	说明
`current`	`str \| None`	否	`None`	授权方报告的当前日志代数（如有）。
`expected`	`str \| None`	否	`None`	下一次注册必须使用的日志代数（如有）。

属性

名称	类型	说明
`readonly currentJournalGeneration?`	`${bigint}`	当前日志代数（冲突应答中含有时提供）。
`readonly expectedJournalGeneration?`	`${bigint}`	下一次注册必须使用的日志代数（冲突应答中含有时提供）。

RuntimeRegistrationLeaseExpiredError

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

授权方返回了已经过期的租约。

class RuntimeRegistrationLeaseExpiredError extends Error
new RuntimeRegistrationLeaseExpiredError()

RuntimeRegistrationOwnerResetRequiredError

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

因日志存储变更而没有显式的所有者重置授权，注册被拒绝。这是终态：重试同一意图只会无限循环，应交给运维人员处理而不是重试。

class RuntimeRegistrationOwnerResetRequiredError extends Error
new RuntimeRegistrationOwnerResetRequiredError()

错误与异常

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

错误	语言	说明
RuntimeRegistrationError	Python	描述注册结果的各错误的基类。
RuntimeRegistrationHandoffRequiredError	TypeScript, Python	上一个租约仍占有该实例。等它过期后，再次注册同一注册意图。
RuntimeRegistrationIntentConflict	Python	已保存的注册 ID 与正在发送的注册意图不再一致，例如运行时方法列表发生了变化。协调器随后会新建注册 ID 并推进日志代数。
RuntimeRegistrationJournalAdvanceRequiredError	TypeScript, Python	上一个租约已过期，下一次注册必须使用下一代日志代数。重试前把持久身份精确推进一次；不要把它当作交接等待。
RuntimeRegistrationLeaseExpiredError	TypeScript	授权方返回了已经过期的租约。
RuntimeRegistrationOwnerResetRequiredError	TypeScript, Python	因日志存储变更而没有显式的所有者重置授权，注册被拒绝。这是终态：重试同一意图只会无限循环，应交给运维人员处理而不是重试。

BeeOS Cloud返回文档首页