BEEOS CLOUD / DEVELOPER REFERENCE

附录：类型与枚举

Harness SDK 的全部共享类型结构与枚举

附录收录前面各页引用的全部共享类型结构与枚举。对象和联合类型可从字段表的类型列跳转到这里；每个类型与枚举都有稳定锚点（标题的小写形式）。

枚举

MSConnectionStatus

TypeScript

harness 与 Cloud 之间实时连接的状态。harness 在心跳中上报。

取值	含义
`unknown`	状态未知。
`connecting`	harness 正在连接。
`connected`	连接已建立。
`reconnecting`	连接已断开，harness 正在重连。
`disconnected`	连接已关闭。
`failed`	连接失败。

RuntimeCapability

TypeScript

harness 可在注册中声明的能力。

取值	含义
`transport`	从 Cloud 接收运行时方法。
`agents.lifecycle`	创建、更新和删除智能体。
`skills`	管理智能体的技能。
`models`	列出可用的模型。
`cron`	管理定时任务。
`mcp`	管理 MCP 服务器。
`conversation.control`	控制会话：提示、取消、清除、模式与模型。
`terminal`	提供终端。
`canvas`	提供画布。
`subagents`	运行子智能体。

RuntimeChatConnectionState

TypeScript

聊天客户端实时连接的状态。

取值	含义
`connected`	连接已建立。
`connecting`	客户端正在连接。
`disconnected`	连接已关闭。
`failed`	连接失败。

RuntimeMethod

TypeScript 与 Python

Cloud 可能投递给 harness 的运行时方法。每条用户聊天提示都以 session/prompt 到达。

取值	常量名	含义
`agent/create`	`AGENT_CREATE`	创建智能体（能力 `agents.lifecycle`）。
`agent/update`	`AGENT_UPDATE`	更新智能体（能力 `agents.lifecycle`）。
`agent/delete`	`AGENT_DELETE`	删除智能体（能力 `agents.lifecycle`）。
`agent/applyTemplate`	`AGENT_APPLY_TEMPLATE`	把模板应用到智能体（能力 `agents.lifecycle`）。
`skills/list`	`SKILLS_LIST`	列出智能体的技能（能力 `skills`）。
`skills/install`	`SKILLS_INSTALL`	安装技能（能力 `skills`）。
`skills/update`	`SKILLS_UPDATE`	启用或停用技能（能力 `skills`）。
`skills/uninstall`	`SKILLS_UNINSTALL`	卸载技能（能力 `skills`）。
`models/list`	`MODELS_LIST`	列出可用的模型（能力 `models`）。
`cron/list`	`CRON_LIST`	列出智能体的定时任务（能力 `cron`）。
`cron/status`	`CRON_STATUS`	读取调度器的状态（能力 `cron`）。
`cron/add`	`CRON_ADD`	添加定时任务（能力 `cron`）。
`cron/update`	`CRON_UPDATE`	更新定时任务（能力 `cron`）。
`cron/remove`	`CRON_REMOVE`	移除定时任务（能力 `cron`）。
`cron/run`	`CRON_RUN`	立即运行一个定时任务（能力 `cron`）。
`cron/runs`	`CRON_RUNS`	列出定时任务的运行记录（能力 `cron`）。
`mcp/list`	`MCP_LIST`	列出 MCP 服务器（能力 `mcp`）。
`mcp/prepare`	`MCP_PREPARE`	准备 MCP 服务器配置（能力 `mcp`）。
`mcp/set`	`MCP_SET`	设置 MCP 服务器（能力 `mcp`）。
`mcp/unset`	`MCP_UNSET`	移除 MCP 服务器（能力 `mcp`）。
`session/set_mode`	`SESSION_SET_MODE`	设置会话的模式（能力 `conversation.control`）。
`session/set_model`	`SESSION_SET_MODEL`	设置会话的模型（能力 `conversation.control`）。
`session/clear`	`SESSION_CLEAR`	清除会话的历史（能力 `conversation.control`）。
`session/cancel`	`SESSION_CANCEL`	取消会话中正在运行的提示（能力 `conversation.control`）。
`session/prompt`	`SESSION_PROMPT`	投递一条用户聊天提示（能力 `conversation.control`）。每条聊天提示都以此方法到达。
`canvas/toggle`	`CANVAS_TOGGLE`	切换画布的显示（能力 `canvas`）。
`canvas/clear`	`CANVAS_CLEAR`	清空画布（能力 `canvas`）。
`canvas/reference`	`CANVAS_REFERENCE`	画布方法 `canvas/reference`（能力 `canvas`）。
`canvas/dimensions`	`CANVAS_DIMENSIONS`	画布方法 `canvas/dimensions`（能力 `canvas`）。

结构

AgentGatewayClientOptions

TypeScript · 仅 TypeScript

Agent Gateway 客户端的选项。

字段	类型	必填	说明
`baseUrl`	`string`	是	Agent Gateway 的基础 URL。
`identity`	AgentRequestIdentity	是	为每个请求签名的身份。
`retry?`	BackoffPolicy \| false	否	幂等调用的默认重试策略；`false` 表示关闭。默认 `TRANSIENT_BACKOFF`。
`onRetry?`	`(info: { method: string; path: string; attempt: number; delayMs: number; error: unknown }) => void`	否	每次重试前调用，参数为方法、路径、第几次尝试、延迟（毫秒）和错误。

AgentKeyPair

TypeScript 与 Python

harness 实例的原始 Ed25519 密钥材料（32 字节公钥 + 32 字节种子）。

字段	类型	必填	说明
`publicKey` / `public_key`	`Uint8Array` / `bytes`	是	原始的 32 字节 Ed25519 公钥。
`privateKey` / `private_key`	`Uint8Array` / `bytes`	是	32 字节的 Ed25519 种子（私钥）。

AnyRuntimeExecutionGrantClaims

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

执行授权的声明。具体结构取决于该授权所允许的方法。

可选形态

#	类型
1	`{ [TMethod in ServiceRuntimeMethod]: RuntimeExecutionGrantClaims<TMethod>; }[ServiceRuntimeMethod]`
2	`{ [TMethod in keyof ConversationRuntimeInvocationResultMap]: ConversationRuntimeExecutionGrantClaims<TMethod>; }[keyof ConversationRuntimeInvocationResultMap]`
3	`{ [TMethod in keyof InstanceRuntimeInvocationResultMap]: InstanceRuntimeExecutionGrantClaims<TMethod>; }[keyof InstanceRuntimeInvocationResultMap]`

BackoffPolicy

TypeScript 与 Python

重试的退避计划：尝试次数上限、延迟和总预算。

字段	类型	必填	说明
`readonly maxAttempts` / `max_attempts`	`number` / `float`	是	总尝试次数（含第一次）。`Infinity` 表示一直重试，直到用完 `budgetMs` 或 `signal` 中止。
`readonly initialDelayMs` / `initial_delay_ms`	`number` / `int`	是	第二次尝试之前的延迟，单位毫秒。
`readonly maxDelayMs` / `max_delay_ms`	`number` / `int`	是	单次延迟的上限，单位毫秒。
`readonly factor`	`number` / `float`	是	每次尝试后延迟所乘的系数。
`readonly budgetMs?` / `budget_ms`	`number` / `int \| None`	否	总的挂钟时间预算；最后一次尝试可以在预算用尽之前开始，但不会在之后开始。

Base64Url

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

base64url 编码的字符串（字符为 A–Z a–z 0–9 - _）。

type Base64Url = string

CanvasRelayClientOptions

TypeScript · 仅 TypeScript

画布中继客户端的选项。

字段	类型	必填	说明
`relayUrl`	`string`	是	画布令牌中的中继 URL。
`keys`	AgentKeyPair	是	harness 实例的 Ed25519 密钥对。
`agentId?`	`string`	否	写入连接查询串的智能体 ID，可选。
`token?`	`string`	否	写入连接查询串的画布令牌，可选。
`socketFactory?`	(url: string, headers: Record<string, string>) => CanvasRelaySocket	否	创建 WebSocket 的函数。测试时可替换，默认使用 `ws`。

CanvasRelayConnect

Python · 仅 Python

画布中继的连接描述：固定路径和可选的查询值。

字段	类型	必填	说明
`path`	`Literal['/ws/agent']`	是	始终为 `/ws/agent`。
`agentIdQuery`	`NotRequired[str]`	是	查询参数 `agentId` 的值。
`tokenQuery`	`NotRequired[str]`	是	查询参数 `token` 的值。

CentrifugeRealtimePortOptions

TypeScript · 仅 TypeScript

Centrifuge 实时端口的选项。

字段	类型	必填	说明
`factory?`	CentrifugeRealtimeFactory	否	创建 Centrifuge 客户端的函数，测试时可替换。

ConversationHistoryGeneration

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

会话历史的代数，十进制字符串。

type ConversationHistoryGeneration = DecimalUInt64

ConversationRuntimeBoundaryFinishRequest

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

向历史边界报告一次运行结束的请求。

字段	类型	必填	说明
`activeRunRegistrationId`	`string`	是	已结束运行的注册 ID。
`operationId`	OperationId	是	操作的标识。
`requestMessageId`	RuntimeControlMessageId	是	承载该请求的消息的标识。
`conversationId`	PlatformConversationId	是	会话的标识。
`historyGeneration`	ConversationHistoryGeneration	是	会话历史的代数（generation）。历史被清除时会变化。
`runtimeRunId`	`string`	是	运行在 harness 中的标识。
`terminalState`	`"completed" \| "failed" \| "cancelled"`	是	运行的结束方式：`completed`、`failed` 或 `cancelled`。
`source`	`"runtime" \| "recovery"`	是	由谁报告结束：`runtime` 表示正常结束，`recovery` 表示在恢复过程中报告。
`lease`	RuntimeBoundaryLeaseAuthority	是	上报结束的 harness 的租约凭据。

ConversationRuntimeBoundaryStartRequest

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

向历史边界报告一次运行开始的请求。

字段	类型	必填	说明
`operationId`	OperationId	是	操作的标识。
`requestMessageId`	RuntimeControlMessageId	是	承载该请求的消息的标识。
`conversationId`	PlatformConversationId	是	会话的标识。
`historyGeneration`	ConversationHistoryGeneration	是	会话历史的代数（generation）。历史被清除时会变化。
`runtimeRunId`	`string`	是	运行在 harness 中的标识。
`lease`	RuntimeBoundaryLeaseAuthority	是	上报开始的 harness 的租约凭据。

CoreExecutionAuthorization

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

授权一次执行的一对已签名文档：授权（grant）和边界断言（boundary assertion）。

字段	类型	必填	说明
`grant`	`RuntimeExecutionGrantEnvelope`	是	执行授权。
`boundary`	`RuntimeExecutionBoundaryAssertion`	是	执行边界断言。

DecimalUInt64

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

规范形式的无符号 uint64 十进制数（字符串）。

type DecimalUInt64 = `${bigint}`

GatewayA2aRpcResult

TypeScript · 仅 TypeScript

一次智能体间 JSON-RPC 调用的结果。

字段	类型	必填	说明
`ok`	`boolean`	是	HTTP 状态为成功时为 `true`。
`status`	`number`	是	应答的 HTTP 状态码。
`body`	`string`	是	原始响应体。
`rpc`	`Record<string, unknown>`	是	按 JSON-RPC 对象解析后的响应体。

GatewayBridgeConfig

TypeScript · 仅 TypeScript

Agent Gateway 返回的终端桥接位置。

字段	类型	必填	说明
`url`	`string`	是	终端桥接的 URL。
`region?`	`string`	否	桥接所在区域；Agent Gateway 给出时才有。

GatewayCanvasToken

TypeScript · 仅 TypeScript

画布令牌及其所属的中继。

字段	类型	必填	说明
`token`	`string`	是	画布令牌。
`relayUrl`	`string`	是	画布中继的 URL。
`expiresAt`	`number`	是	令牌的过期时间（Unix 时间戳）。

GatewayFileRef

TypeScript · 仅 TypeScript

对挂在智能体上的文件的引用。

字段	类型	必填	说明
`fileId`	`string`	是	文件的标识。
`fileName`	`string`	是	文件名。
`mimeType?`	`string`	否	文件的 MIME 类型。
`size?`	`number`	否	大小，单位字节。
`source?`	`string`	否	文件的来源。

GatewayFileResolve

TypeScript · 仅 TypeScript

解析文件 ID 时返回的文件详情。

字段	类型	必填	说明
`fileId?`	`string`	否	文件的标识。
`fileName?`	`string`	否	文件名。
`mimeType?`	`string`	否	文件的 MIME 类型。
`size?`	`number`	否	大小，单位字节。
`downloadUrl?`	`string`	否	可下载该文件的 URL。
`[key: string]`	`unknown`	是	Agent Gateway 返回的其他字段。

GatewayPresign

TypeScript · 仅 TypeScript

新文件的上传位置。

字段	类型	必填	说明
`fileId`	`string`	是	新文件的标识。上传完成后传给确认调用。
`uploadUrl`	`string`	是	文件内容需要上传到的 URL。

GatewayRequestInit

TypeScript · 仅 TypeScript

Agent Gateway 请求的单次调用选项，基于标准的 RequestInit。

继承: Omit<RequestInit, "body">

字段	类型	必填	说明
`body?`	`string \| Uint8Array`	否	请求体。
`retry?`	BackoffPolicy \| false	否	覆盖客户端默认值；`false` 表示本次调用不重试。
`idempotent?`	`boolean`	否	允许重试 Agent Gateway 会去重的非 GET 调用。

GatewayUploadedFile

TypeScript · 仅 TypeScript

文件上传完成后的结果。

字段	类型	必填	说明
`fileId`	`string`	是	文件的标识。
`uri`	`string`	是	已上传文件的 URI。
`fileName`	`string`	是	文件名。
`mimeType`	`string`	是	文件的 MIME 类型。

HistoryBoundaryAction

TypeScript · 仅 TypeScript

历史边界动作的名称：prepare、resetting、reset_done、commit、abort 或 reconcile。

type HistoryBoundaryAction = keyof typeof HISTORY_BOUNDARY_OPERATIONS

JsonValue

TypeScript · 仅 TypeScript

任意 JSON 值：null、布尔、数字、字符串、数组或对象。

可选形态

#	类型
1	`null`
2	`boolean`
3	`number`
4	`string`
5	JsonValue[]
6	{ [key: string]: JsonValue }

可选形态 6

字段	类型	必填	说明
`[key: string]`	JsonValue	是	对象的各个值，按键索引。

MessageServiceMessageId

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

Message Service 中调用方或运行时使用的幂等键；不透明、长度有限，且不是平台 UUID。

type MessageServiceMessageId = string

OperationId

TypeScript · 仅 TypeScript

操作的标识：HARNESS_OPERATIONS 的键。

type OperationId = keyof typeof OPERATIONS

OperationPathParams

TypeScript · 仅 TypeScript

每个操作的路径参数，按操作 ID 索引。

字段	类型	必填	说明
`runtimeRegister`	`Record<never, never>`	是	`runtimeRegister` 的路径参数：无。
`runtimeHeartbeat`	`{ registrationId: string }`	是	`runtimeHeartbeat` 的路径参数：`registrationId`。
`runtimeRealtimeTokenCreate`	`Record<never, never>`	是	`runtimeRealtimeTokenCreate` 的路径参数：无。
`runtimeConversationSync`	`Record<never, never>`	是	`runtimeConversationSync` 的路径参数：无。
`runtimeConversationMessagesList`	`{ conversationId: string }`	是	`runtimeConversationMessagesList` 的路径参数：`conversationId`。
`runtimeConversationMessageCreate`	`{ conversationId: string }`	是	`runtimeConversationMessageCreate` 的路径参数：`conversationId`。
`runtimeConversationMessageGet`	`{ conversationId: string; messageId: string }`	是	`runtimeConversationMessageGet` 的路径参数：`conversationId`, `messageId`。
`runtimeConversationMessagePatch`	`{ conversationId: string; messageId: string }`	是	`runtimeConversationMessagePatch` 的路径参数：`conversationId`, `messageId`。
`runtimeConversationRunStart`	`{ conversationId: string }`	是	`runtimeConversationRunStart` 的路径参数：`conversationId`。
`runtimeConversationRunFinish`	`{ conversationId: string }`	是	`runtimeConversationRunFinish` 的路径参数：`conversationId`。
`runtimeDeliveriesRead`	`Record<never, never>`	是	`runtimeDeliveriesRead` 的路径参数：无。
`runtimeDeliveriesRenew`	`Record<never, never>`	是	`runtimeDeliveriesRenew` 的路径参数：无。
`runtimeDeliveriesAck`	`Record<never, never>`	是	`runtimeDeliveriesAck` 的路径参数：无。
`runtimeOperationHistoryGet`	`{ operationId: string }`	是	`runtimeOperationHistoryGet` 的路径参数：`operationId`。
`runtimeOperationMessageAppend`	`{ operationId: string }`	是	`runtimeOperationMessageAppend` 的路径参数：`operationId`。
`conversationMessagesList`	`{ conversationId: string }`	是	`conversationMessagesList` 的路径参数：`conversationId`。
`conversationMessageSend`	`{ conversationId: string }`	是	`conversationMessageSend` 的路径参数：`conversationId`。
`agentGet`	`{ agentId: string }`	是	`agentGet` 的路径参数：`agentId`。
`agentUpdate`	`{ agentId: string }`	是	`agentUpdate` 的路径参数：`agentId`。
`agentSync`	`Record<never, never>`	是	`agentSync` 的路径参数：无。
`agentFilesList`	`Record<never, never>`	是	`agentFilesList` 的路径参数：无。
`agentFilePresign`	`Record<never, never>`	是	`agentFilePresign` 的路径参数：无。
`agentFileConfirm`	`Record<never, never>`	是	`agentFileConfirm` 的路径参数：无。
`agentFileResolve`	`{ fileId: string }`	是	`agentFileResolve` 的路径参数：`fileId`。
`canvasTokenCreate`	`Record<never, never>`	是	`canvasTokenCreate` 的路径参数：无。
`a2aDiscover`	`Record<never, never>`	是	`a2aDiscover` 的路径参数：无。
`a2aJsonRpc`	`{ agentId: string }`	是	`a2aJsonRpc` 的路径参数：`agentId`。
`a2aTaskGet`	`{ taskId: string }`	是	`a2aTaskGet` 的路径参数：`taskId`。
`messagingTokenCreate`	`Record<never, never>`	是	`messagingTokenCreate` 的路径参数：无。
`runtimeHistoryBoundaryPrepare`	`{ conversationId: string }`	是	`runtimeHistoryBoundaryPrepare` 的路径参数：`conversationId`。
`runtimeHistoryBoundaryResetting`	`{ conversationId: string }`	是	`runtimeHistoryBoundaryResetting` 的路径参数：`conversationId`。
`runtimeHistoryBoundaryResetDone`	`{ conversationId: string }`	是	`runtimeHistoryBoundaryResetDone` 的路径参数：`conversationId`。
`runtimeHistoryBoundaryCommit`	`{ conversationId: string }`	是	`runtimeHistoryBoundaryCommit` 的路径参数：`conversationId`。
`runtimeHistoryBoundaryAbort`	`{ conversationId: string }`	是	`runtimeHistoryBoundaryAbort` 的路径参数：`conversationId`。
`runtimeHistoryBoundaryReconcile`	`{ conversationId: string }`	是	`runtimeHistoryBoundaryReconcile` 的路径参数：`conversationId`。
`runtimeConversationMetadataModel`	`{ conversationId: string }`	是	`runtimeConversationMetadataModel` 的路径参数：`conversationId`。
`runtimeConversationCronDelivery`	`{ conversationId: string }`	是	`runtimeConversationCronDelivery` 的路径参数：`conversationId`。
`runtimeClaimNext`	`Record<never, never>`	是	`runtimeClaimNext` 的路径参数：无。
`runtimeClaimExact`	`{ operationId: string }`	是	`runtimeClaimExact` 的路径参数：`operationId`。
`runtimeClaimRenew`	`{ operationId: string }`	是	`runtimeClaimRenew` 的路径参数：`operationId`。
`runtimeClaimRelease`	`{ operationId: string }`	是	`runtimeClaimRelease` 的路径参数：`operationId`。
`runtimeResourceRedeem`	`{ operationId: string; kind: string; resourceRef: string }`	是	`runtimeResourceRedeem` 的路径参数：`operationId`, `kind`, `resourceRef`。
`runtimeOutputFilePresign`	`{ operationId: string }`	是	`runtimeOutputFilePresign` 的路径参数：`operationId`。
`runtimeOutputFileConfirm`	`{ operationId: string }`	是	`runtimeOutputFileConfirm` 的路径参数：`operationId`。
`runtimeInputFilesResolve`	`{ operationId: string }`	是	`runtimeInputFilesResolve` 的路径参数：`operationId`。
`agentTemplateOriginReport`	`{ agentId: string }`	是	`agentTemplateOriginReport` 的路径参数：`agentId`。
`channelCreate`	`Record<never, never>`	是	`channelCreate` 的路径参数：无。
`a2aTaskComplete`	`{ taskId: string }`	是	`a2aTaskComplete` 的路径参数：`taskId`。
`agentEventPublish`	`Record<never, never>`	是	`agentEventPublish` 的路径参数：无。
`bridgeConfigGet`	`Record<never, never>`	是	`bridgeConfigGet` 的路径参数：无。
`agentConnectorMcp`	`Record<never, never>`	是	`agentConnectorMcp` 的路径参数：无。
`automationList`	`Record<never, never>`	是	`automationList` 的路径参数：无。
`automationCreate`	`Record<never, never>`	是	`automationCreate` 的路径参数：无。
`automationWebhookCreate`	`Record<never, never>`	是	`automationWebhookCreate` 的路径参数：无。
`automationGet`	`{ automationId: string }`	是	`automationGet` 的路径参数：`automationId`。
`automationRunsList`	`{ automationId: string }`	是	`automationRunsList` 的路径参数：`automationId`。
`automationRunCreate`	`{ automationId: string }`	是	`automationRunCreate` 的路径参数：`automationId`。
`automationRunGet`	`{ automationId: string; runId: string }`	是	`automationRunGet` 的路径参数：`automationId`, `runId`。

PlatformAgentId

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

智能体的标识：UUID 字符串。

type PlatformAgentId = PlatformResourceId

PlatformConversationId

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

会话的标识：UUID 字符串。

type PlatformConversationId = PlatformResourceId

PlatformInstanceId

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

Cloud 实例的标识：inst_ 加 24 位小写十六进制字符。

type PlatformInstanceId = string

PlatformResourceId

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

Cloud 资源的标识：UUID 字符串。

type PlatformResourceId = string

RetryOptions

TypeScript · 仅 TypeScript

retryWithBackoff 的选项。

字段	类型	必填	说明
`policy`	BackoffPolicy	是	使用的退避计划。
`isRetryable?`	`(error: unknown) => boolean`	否	判断某个错误是否值得重试。默认对所有错误重试。
`signal?`	`AbortSignal`	否	中止等待并停止重试。
`onRetry?`	`(info: { attempt: number; delayMs: number; error: unknown }) => void`	否	每次重试前调用，参数为第几次尝试、延迟（毫秒）和错误。
`sleep?`	`(ms: number, signal?: AbortSignal) => Promise<void>`	否	等待给定的毫秒数，测试时可替换。
`now?`	`() => number`	否	毫秒时钟，测试时可替换。

RFC3339Timestamp

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

RFC 3339 格式的时间戳字符串。

type RFC3339Timestamp = string

RuntimeActiveLease

TypeScript 与 Python

注册协调器所报告的当前生效租约。

字段	类型	必填	说明
`instanceId` / `instance_id`	`string` / `str`	是	harness 所注册到的 Cloud 实例的标识。
`leaseId` / `lease_id`	`string` / `str`	是	运行时租约的标识。
`runtimeEpoch` / `runtime_epoch`	`${bigint}` / `str`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`runtimeLeaseCredential` / `runtime_lease_credential`	`string` / `str`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。
`leaseExpiresAt` / `lease_expires_at`	`string` / `str`	是	租约过期的时间（RFC 3339 时间戳）。
`heartbeat_interval_ms`	`int`	否	租约必须续期的间隔，单位毫秒。
`registration_id`	`str`	否	注册的标识。
`handler_identity`	`str`	否	持有该租约的处理方的身份。

RuntimeBoundaryLeaseAuthority

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

harness 向历史边界汇报时用来证明其权限的租约信息。

字段	类型	必填	说明
`leaseId`	`string`	是	运行时租约的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	RuntimeEpoch	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`runtimeLeaseCredential`	`string`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。

RuntimeChatClientOptions

TypeScript · 仅 TypeScript

运行时聊天客户端的选项。

字段	类型	必填	说明
`authority`	RuntimeChatAuthorityPort	是	提供当前租约。
`http`	RuntimeChatHttpPort	是	用于聊天调用的 HTTP 端口。
`realtime`	RuntimeChatRealtimePort	是	用于接收新消息的实时端口。
`now?`	`() => number`	否	毫秒时钟，测试时可替换，默认 `Date.now`。
`reconnectDelayMs?`	`(attempt: number) => number`	否	重连的退避延迟，有上限；`attempt` 从 1 开始。
`logger?`	RuntimeChatLogger	否	接收日志消息，可选。

RuntimeChatHistoryInput

TypeScript · 仅 TypeScript

读取会话历史的分页选项。

字段	类型	必填	说明
`cursor?`	`string`	否	上一页返回的游标。
`limit?`	`number`	否	最多返回的条目数。

RuntimeChatHistoryMessage

TypeScript · 仅 TypeScript

历史页中的一条消息。

继承: RuntimeChatMessage

字段	类型	必填	说明
`offset?`	`string`	否	消息在会话中的位置，十进制字符串。
`historyGeneration?`	`string`	否	消息所属的历史代数。
`state?`	`string`	否	消息的状态，例如 `streaming` 或 `completed`。
`stopReason?`	`string`	否	消息停止的原因。
`body?`	`string`	否	消息文本。
`parts?`	`readonly unknown[]`	否	消息的结构化片段。

RuntimeChatHistoryPage

TypeScript · 仅 TypeScript

会话历史的一页。

字段	类型	必填	说明
`messages`	RuntimeChatHistoryMessage[]	是	本页的消息。
`nextCursor?`	`string`	否	下一页的游标。最后一页没有。
`hasMore`	`boolean`	是	还有后续页时为 `true`。
`latestOffset`	`string`	是	会话中最新消息的偏移。
`historyGeneration`	`string`	是	历史的当前代数。
`historyBoundaryOffset`	`string`	是	当前历史代数的起始偏移。

RuntimeChatHttpPortOptions

TypeScript · 仅 TypeScript

聊天客户端所用 HTTP 端口的选项。

字段	类型	必填	说明
`baseUrl`	`string`	是	Message Service 的来源（origin），例如 `https://message.example`。
`fetchImpl?`	`typeof fetch`	否	用于 HTTP 调用的函数，默认是全局 `fetch`。
`now?`	`() => number`	否	毫秒时钟，测试时可替换，默认 `Date.now`。

RuntimeChatLease

TypeScript · 仅 TypeScript

聊天客户端所需的租约信息。

字段	类型	必填	说明
`instanceId`	`string`	是	harness 所注册到的 Cloud 实例的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	`string`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`leaseId`	`string`	是	运行时租约的标识。
`runtimeLeaseCredential`	`string`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。
`leaseExpiresAt`	`string`	是	租约过期的时间（RFC 3339 时间戳）。

RuntimeChatLogger

TypeScript · 仅 TypeScript

聊天客户端的日志器，每个方法都是可选的。

字段	类型	必填	说明
`debug?`	`(...args: unknown[]) => void`	否	接收调试消息。
`info?`	`(...args: unknown[]) => void`	否	接收信息消息。
`warn?`	`(...args: unknown[]) => void`	否	接收警告。
`error?`	`(...args: unknown[]) => void`	否	接收错误。

RuntimeChatMessage

TypeScript · 仅 TypeScript

一条会话消息。

字段	类型	必填	说明
`id`	`string`	是	消息的标识。
`conversationId`	`string`	是	会话的标识。
`type`	`string`	是	消息的类型，例如 `agent_reply`。
`content`	`unknown`	是	消息内容。
`senderId?`	`string`	否	发送者的标识。
`replyTo?`	`string`	否	本消息所回复的消息的标识。
`createdAt?`	`string`	否	消息创建的时间。
`[key: string]`	`unknown`	是	Cloud 返回的其他字段。

RuntimeChatPreparedClearProof

TypeScript · 仅 TypeScript

历史清除已经准备好的证明。在修改保留的回复之前会先检查它。

字段	类型	必填	说明
`clearIntentId`	`string`	是	清除意图的标识。
`activeRunRegistrationId`	`string`	是	当前运行的注册 ID。
`historyGeneration`	`${bigint}`	是	会话历史的代数（generation）。历史被清除时会变化。
`runtimeEpoch`	`${bigint}`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。

RuntimeChatRetainedBinding

TypeScript · 仅 TypeScript

把保留的回复绑定到它的会话和消息，以及修改时要执行的检查。

字段	类型	必填	说明
`conversationId`	`string`	是	会话的标识。
`messageId`	`string`	是	回复消息的标识。
`taskRequestMessageId`	`string`	是	原始任务请求的消息 ID，与操作 RPC 请求消息不同。
`assertAttempt`	`() => void`	是	由可信的日志所有者提供，绝不从提示内容推断。
`mutationKey`	`(sequence: number) => string`	是	由所属尝试提供的稳定幂等键，每个串行化的修改一个。
`assertPreparedClear?`	(proof: RuntimeChatPreparedClearProof) => void	否	以已准备好的清除证明为参数调用；抛出错误则拒绝本次修改。

RuntimeChatRetainedSnapshot

TypeScript · 仅 TypeScript

回复消息的已存副本。

字段	类型	必填	说明
`rawText`	`string`	是	读取时消息的原始 JSON 文本。
`messageId`	`string`	是	消息的标识。
`conversationId`	`string`	是	会话的标识。
`type`	`string`	是	消息的类型。
`sender`	`string`	是	发送者的标识。
`createdAt`	`string`	是	消息创建的时间。
`updatedAt?`	`string`	否	消息最后更新的时间。
`replyTo?`	`string`	否	本消息所回复的消息的标识。
`body`	`string`	是	消息文本。
`state`	`string`	是	消息的状态：`streaming`、`completed`、`failed`、`refused` 或 `cancelled`。
`stopReason?`	`string`	否	消息停止的原因。

RuntimeChatSendInput

TypeScript · 仅 TypeScript

发送消息的输入。

字段	类型	必填	说明
`conversationId`	`string`	是	会话的标识。
`id?`	`string`	否	新消息的标识。省略时由 Cloud 生成。
`type`	`string`	是	消息的类型，例如 `agent_reply`。
`content`	`unknown`	是	消息内容。
`replyTo?`	`string`	否	本消息所回复的消息的标识。

RuntimeClaimExactRequest

TypeScript · 仅 TypeScript

认领指定的某个操作的请求。

继承: RuntimeClaimNextRequest

字段	类型	必填	说明
`operationId`	`string`	是	操作的标识。
`requestMessageId`	`string`	是	承载该请求的消息的标识。
`dispatchEpoch`	`string`	是	Cloud 派发该操作时的 epoch。

RuntimeClaimFence

TypeScript · 仅 TypeScript

认领的 fence：证明 harness 仍然拥有该操作。

字段	类型	必填	说明
`claimId`	`string`	是	认领（claim）的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	`string`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`fencingToken`	`string`	是	认领的 fencing token（十进制字符串）。比当前值小的令牌已过期。
`journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`journalGeneration`	`string`	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。
`operationId`	`string`	是	操作的标识。
`requestMessageId`	`string`	是	承载该请求的消息的标识。
`runtimeLeaseCredential`	`string`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。

RuntimeClaimNextRequest

TypeScript · 仅 TypeScript

认领下一个待处理操作的请求。

字段	类型	必填	说明
`claimRequestId`	`string`	是	本次认领请求的标识，用于去重。
`instanceId`	`string`	是	harness 所注册到的 Cloud 实例的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	`string`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`journalGeneration`	`string`	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。
`runtimeLeaseCredential`	`string`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。

RuntimeClaimReleaseRequest

TypeScript · 仅 TypeScript

释放某个操作的认领的请求。

继承: RuntimeClaimFence

字段	类型	必填	说明
`reason`	`"completed" \| "cancelled" \| "worker_shutdown" \| "claim_rejected"`	是	释放认领的原因：`completed`、`cancelled`、`worker_shutdown` 或 `claim_rejected`。

RuntimeClaimRenewRequest

TypeScript · 仅 TypeScript

为某个操作的认领续期的请求。

继承: RuntimeClaimFence

没有字段。

RuntimeControlMessageId

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

运行时控制面在 Message Service 中的消息 ID，遵循同样的有界不透明规则。

type RuntimeControlMessageId = string

RuntimeConversationSyncRequest

Python · 仅 Python

创建或更新某个操作的会话的请求。

字段	类型	必填	说明
`schemaVersion`	`Literal[1]`	是	请求结构的版本，始终为 `1`。
`operationId`	`str`	是	操作的标识。
`runtimeSessionId`	`str`	是	会话在 harness 中的标识。
`runtimeSessionKey`	`NotRequired[str]`	是	会话在 harness 中的 key。
`title`	`NotRequired[str]`	是	会话的标题。

RuntimeDeliveriesReadRequest

Python · 仅 Python

读取待处理投递的请求。

字段	类型	必填	说明
`schemaVersion`	`Literal[1]`	是	请求结构的版本，始终为 `1`。
`maxCount`	`int`	是	最多返回的投递数。
`blockMs`	`int`	是	没有待处理投递时的最长等待时间，单位毫秒。

RuntimeDeliveryAppendReceipt

TypeScript · 仅 TypeScript

向某个操作追加消息的结果。

可选形态

#	类型
1	{ readonly outcome: "created" \| "duplicate" \| "reconciled"; readonly message?: JsonValue; readonly history?: JsonValue }
2	{ readonly outcome: "outcome_unknown"; readonly history?: JsonValue }

可选形态 1

字段	类型	必填	说明
`readonly outcome`	`"created" \| "duplicate" \| "reconciled"`	是	`created` 表示新消息，`duplicate` 表示已存储过，`reconciled` 表示先前不确定的追加已得到确认。
`readonly message?`	JsonValue	否	已存储的消息。
`readonly history?`	JsonValue	否	该操作的历史；Cloud 返回时才有。

可选形态 2

字段	类型	必填	说明
`readonly outcome`	`"outcome_unknown"`	是	`outcome_unknown`：追加可能已存储，也可能没有。
`readonly history?`	JsonValue	否	该操作的历史；Cloud 返回时才有。

RuntimeDeliveryAuthorityLease

TypeScript · 仅 TypeScript

投递端口所需的租约凭据。

继承: RuntimeDeliveryLease

字段	类型	必填	说明
`readonly runtimeLeaseCredential`	`string`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。

RuntimeDeliveryConsumeOptions

TypeScript · 仅 TypeScript

投递消费循环的选项。

字段	类型	必填	说明
`readonly onDelivery`	(delivery: RuntimeMethodDelivery, context: { readonly lease: RuntimeDeliveryLease; readonly signal: AbortSignal }) => Promise<void>	是	处理一条投递。处理函数返回时确认该投递，抛出错误时留待重新投递。
`readonly onError?`	`(error: unknown) => void`	否	循环自行处理的错误会通过它通知。
`readonly onLeaseStarvation?`	`(input: { readonly starvedForMs: number; readonly recovered: boolean }) => void`	否	一段时间内没有有效租约时调用。
`readonly readCount?`	`number`	否	单次最多读取的投递数。
`readonly blockMs?`	`number`	否	单次读取等待投递的时间，单位毫秒。
`readonly idleDelayMs?`	`number`	否	没有投递时再次读取之前的停顿，单位毫秒。
`readonly renewIntervalMs?`	`number`	否	仍在处理的投递的续期频率，单位毫秒。

RuntimeDeliveryHistory

TypeScript · 仅 TypeScript

某个操作的历史：已找到、未找到或已过期。

可选形态

#	类型
1	`{ readonly status: "not_found" \| "expired" }`
2	{ readonly status: "found"; readonly snapshot: JsonValue }

可选形态 1

字段	类型	必填	说明
`readonly status`	`"not_found" \| "expired"`	是	`not_found` 表示操作未知，`expired` 表示其历史已不再保留。

可选形态 2

字段	类型	必填	说明
`readonly status`	`"found"`	是	`found`：历史在 `snapshot` 中。
`readonly snapshot`	JsonValue	是	已存储的历史。

RuntimeDeliveryIdsRequest

Python · 仅 Python

按 ID 指明投递的请求。

字段	类型	必填	说明
`schemaVersion`	`Literal[1]`	是	请求结构的版本，始终为 `1`。
`deliveryIds`	`list[str]`	是	投递的标识列表。

RuntimeDeliveryLease

TypeScript · 仅 TypeScript

处理投递时所依据的租约，包括它所属的日志。

字段	类型	必填	说明
`readonly instanceId`	`string`	是	harness 所注册到的 Cloud 实例的标识。
`readonly handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`readonly runtimeEpoch`	`string`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`readonly leaseId`	`string`	是	运行时租约的标识。
`readonly leaseExpiresAt`	`string`	是	租约过期的时间（RFC 3339 时间戳）。
`readonly journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`readonly journalGeneration`	`string`	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。

RuntimeEpoch

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

运行时注册的 epoch，十进制字符串。

type RuntimeEpoch = DecimalUInt64

RuntimeExecutionBoundaryAssertionClaims

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

执行边界断言的声明：Cloud 签发的、允许某次执行开始或恢复的签名声明。

字段	类型	必填	说明
`iss`	`string`	是	令牌的签发方（JWT 的 `iss`）。
`aud`	`typeof RUNTIME_EXECUTION_BOUNDARY_AUDIENCE`	是	令牌的受众（JWT 的 `aud`）。
`sub`	`string`	是	令牌的主体（JWT 的 `sub`）。
`jti`	`string`	是	令牌的唯一 ID（JWT 的 `jti`）。
`iat`	`number`	是	签发时间（Unix 秒，JWT 的 `iat`）。
`exp`	`number`	是	过期时间（Unix 秒，JWT 的 `exp`）。
`executionMode`	`"start" \| "resume"`	是	`start` 表示新的执行，`resume` 表示延续先前的执行。
`executionBoundaryId`	`string`	是	执行边界的标识。
`predecessorExecutionBoundaryId?`	`string`	否	本次执行所延续的那次执行的边界 ID。`start` 时不存在，`resume` 时必须有，并被签入断言。
`handoffId?`	`string`	否	交接（handoff）的标识，用于恢复的执行。
`operationId`	OperationId	是	操作的标识。
`requestMessageId`	RuntimeControlMessageId	是	承载该请求的消息的标识。
`commandHash`	Sha256HexDigest	是	命令的 SHA-256 摘要（64 位小写十六进制）。
`executionGrantHash`	Sha256HexDigest	是	执行授权的 SHA-256 摘要（64 位小写十六进制）。
`claimId`	`string`	是	认领（claim）的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	RuntimeEpoch	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`fencingToken`	RuntimeFencingToken	是	认领的 fencing token（十进制字符串）。比当前值小的令牌已过期。
`journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`journalGeneration`	RuntimeRevision	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。
`journalRevisionBeforeAttempt`	RuntimeRevision	是	本次尝试开始之前日志的修订号。
`preparedEntryHash`	Sha256HexDigest	是	为本次尝试准备的日志条目的 SHA-256 摘要。

RuntimeFencingToken

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

fencing token，十进制字符串。

type RuntimeFencingToken = DecimalUInt64

RuntimeHeartbeatRequest

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

为租约续期的心跳请求。

继承: RuntimeIdentityProof<"runtime.heartbeat">

字段	类型	必填	说明
`targetInstanceId?`	`string`	否	该注册必须属于的 Cloud 实例。
`leaseId`	`string`	是	运行时租约的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	RuntimeEpoch	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`msConnectionStatus?`	MSConnectionStatus	否	harness 所观察到的自身实时连接的状态。

RuntimeHeartbeatResult

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

心跳的应答：已续期、已被 fence 或已过期。

可选形态

#	类型
1	{ status: "renewed"; leaseExpiresAt: RFC3339Timestamp; runtimeLeaseCredential: string; }
2	{ status: "fenced"; activeRuntimeEpoch: RuntimeEpoch; }
3	`{ status: "expired"; }`

可选形态 1

字段	类型	必填	说明
`status`	`"renewed"`	是	`renewed`：租约继续有效。
`leaseExpiresAt`	RFC3339Timestamp	是	租约新的过期时间。
`runtimeLeaseCredential`	`string`	是	续期后租约的凭据，此后请使用它。

可选形态 2

字段	类型	必填	说明
`status`	`"fenced"`	是	`fenced`：已有另一个注册处于生效状态。
`activeRuntimeEpoch`	RuntimeEpoch	是	当前生效的注册的 epoch。

可选形态 3

字段	类型	必填	说明
`status`	`"expired"`	是	`expired`：租约已过期，harness 必须重新注册。

RuntimeIdentityProof

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

已签名的证明：注册或心跳来自实例身份密钥的持有者。

字段	类型	必填	说明
`signaturePurpose`	`TPurpose`	是	签名的用途：注册或心跳的证明域。
`instanceIdentityKeyId`	`RuntimeIdentityKeyId`	是	签名所用密钥的标识。
`nonce`	Base64Url	是	一次性随机值。
`signedAt`	RFC3339Timestamp	是	签名时间（RFC 3339 时间戳）。
`payloadHash`	Sha256HexDigest	是	被签名载荷的 SHA-256 摘要（64 位小写十六进制）。
`signature`	Base64Url	是	Ed25519 签名。

RuntimeInvocationExpectedTarget

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

运行时方法的作用对象。scope 为 instance、agent 或 conversation，每种 scope 允许的字段不同。

可选形态

#	类型
1	`{ scope: "instance"; platformAgentId?: never; runtimeAgentUid?: string; runtimeLocalKey?: never; platformConversationId?: never; runtimeConversationUid?: nev...`
2	{ scope: "agent"; platformAgentId: PlatformAgentId; runtimeAgentUid: string; runtimeLocalKey: string; platformConversationId?: never; runtimeConversationUid?...
3	{ scope: "conversation"; platformAgentId: PlatformAgentId; runtimeAgentUid: string; runtimeLocalKey?: never; platformConversationId: PlatformConversationId; ...

可选形态 1

字段	类型	必填	说明
`scope`	`"instance"`	是	`instance`：整个实例。
`platformAgentId?`	`never`	否	该 scope 下不允许出现，必须省略。
`runtimeAgentUid?`	`string`	否	智能体在 harness 内部的标识。
`runtimeLocalKey?`	`never`	否	该 scope 下不允许出现，必须省略。
`platformConversationId?`	`never`	否	该 scope 下不允许出现，必须省略。
`runtimeConversationUid?`	`never`	否	该 scope 下不允许出现，必须省略。
`runtimeSessionKey?`	`never`	否	该 scope 下不允许出现，必须省略。

可选形态 2

字段	类型	必填	说明
`scope`	`"agent"`	是	`agent`：某一个智能体。
`platformAgentId`	PlatformAgentId	是	智能体在 Cloud 中的标识。
`runtimeAgentUid`	`string`	是	智能体在 harness 内部的标识。
`runtimeLocalKey`	`string`	是	智能体在 harness 内部的本地 key。
`platformConversationId?`	`never`	否	该 scope 下不允许出现，必须省略。
`runtimeConversationUid?`	`never`	否	该 scope 下不允许出现，必须省略。
`runtimeSessionKey?`	`never`	否	该 scope 下不允许出现，必须省略。

可选形态 3

字段	类型	必填	说明
`scope`	`"conversation"`	是	`conversation`：某个智能体的一个会话。
`platformAgentId`	PlatformAgentId	是	智能体在 Cloud 中的标识。
`runtimeAgentUid`	`string`	是	智能体在 harness 内部的标识。
`runtimeLocalKey?`	`never`	否	该 scope 下不允许出现，必须省略。
`platformConversationId`	PlatformConversationId	是	会话在 Cloud 中的标识。
`runtimeConversationUid`	`string`	是	会话在 harness 内部的标识。
`runtimeSessionKey`	`string`	是	会话在 harness 内部的 key。

RuntimeInvocationFence

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

执行必须与之匹配的当前认领的 fence。

字段	类型	必填	说明
`claimId`	`string`	是	认领（claim）的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	RuntimeEpoch	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`fencingToken`	RuntimeFencingToken	是	认领的 fencing token（十进制字符串）。比当前值小的令牌已过期。
`journalStoreId`	`string`	是	认领最初针对的日志存储的标识，之后不会再变。
`journalGeneration`	RuntimeRevision	是	日志存储的代数。

RuntimeInvocationMethod

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

可被调用的运行时方法的名称，例如 session/prompt。

可选形态

#	类型
1	`ServiceRuntimeMethod`
2	`InstanceRuntimeInvocationMethod`
3	`ConversationRuntimeInvocationMethod`
4	`InternalRuntimeInvocationMethod`

RuntimeInvocationValidationContext

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

执行授权的校验所依据的上下文：已持久化的调用及其作用对象。

type RuntimeInvocationValidationContext = RuntimeInvocationValidationContextBase & RuntimeInvocationExpectedTarget & ({ method: "session/cancel"; scope: "conversation"; historyGeneration: ConversationHistoryGeneration; targetMessageId: MessageServiceMessageId; } | { method: Exclude<RuntimeInvocationMethod, "session/cancel">; historyGeneration?: never; targetMessageId?: never; })

RuntimeJwksDocumentProvenance

TypeScript · 仅 TypeScript

JWKS 文档的来源及其自述内容。

字段	类型	必填	说明
`sourceUrl`	`string`	是	加载该文档的 URL。
`etag`	`string`	是	响应的 `ETag`。
`issuer`	`string`	是	文档声明的签发方。
`audience`	`string`	是	文档声明的受众。
`purpose`	`string`	是	文档声明的用途。
`maxClaimTtlSeconds`	`number`	是	已签名声明的最长有效期，单位秒。文档未声明时为 `NaN`。

RuntimeJwksFetch

TypeScript · 仅 TypeScript

下载 URL 的函数，签名与 fetch 相同。

type RuntimeJwksFetch = (url: string | URL, init?: RequestInit) => Promise<Response>

RuntimeJwksKeyMaterial

TypeScript · 仅 TypeScript

一个受信公钥的指纹。

字段	类型	必填	说明
`jwkThumbprint`	`string`	是	JWK 形式公钥的 SHA-256 指纹。
`spkiSha256`	`string`	是	SPKI DER 形式公钥的 SHA-256 摘要（十六进制）。

RuntimeLeaseCredential

TypeScript 与 Python

单独的租约凭据。

字段	类型	必填	说明
`runtimeLeaseCredential` / `runtime_lease_credential`	`string` / `str`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。
`executionGrant?` / `execution_grant`	`string` / `str \| None`	否	该操作的执行授权，路由要求时提供。以 `X-BeeOS-Execution-Grant` 发送。
`scopedDeliveryKey?` / `scoped_delivery_key`	`string` / `str \| None`	否	以 `X-Runtime-Delivery-Key` 发送的投递密钥。会话模型和定时任务路由需要。

RuntimeLeaseHttpOptions

TypeScript · 仅 TypeScript

租约 HTTP 客户端的选项。

字段	类型	必填	说明
`origin`	`string`	是	租约只能发送到的固定来源（Message Service 或 Agent Gateway）。
`retry?`	BackoffPolicy \| false	否	单次调用的重试。默认不重试，因为追加或确认的结果可能不明确。
`fetch?`	`typeof fetch`	否	用于 HTTP 调用的函数，默认是全局 `fetch`。

RuntimeMessagePatch

Python · 仅 Python

对正在流式写入的消息的修改。

字段	类型	必填	说明
`body`	`NotRequired[str]`	是	替换整段文本。
`body_append`	`NotRequired[str]`	是	要追加的文本。
`body_from`	`NotRequired[int]`	是	`body_append` 在文本中的起始位置。
`parts`	`NotRequired[list[JsonObject]]`	是	替换结构化片段。
`state`	`NotRequired[str]`	是	新的状态：`streaming`、`completed`、`failed`、`refused` 或 `cancelled`。
`stop_reason`	`NotRequired[str]`	是	消息停止的原因。

RuntimeMethodDelivery

TypeScript 与 Python

从 Cloud 读取的一条运行时方法投递。

字段	类型	必填	说明
`readonly deliveryId` / `delivery_id`	`string` / `str`	是	投递的标识，用于续期和确认。
`readonly redelivered`	`boolean` / `bool`	是	该投递之前已发出过时为 `true`。
`readonly idleMs` / `idle_ms`	`number` / `int`	是	投递在被读取之前等待的时间，单位毫秒。
`readonly message`	JsonValue / `Any`	是	投递所含的消息。
`readonly executionGrant?` / `execution_grant`	`string` / `str \| None`	否	该操作的执行授权，有则提供。

RuntimeNativeConversationSyncRequest

TypeScript · 仅 TypeScript

创建或更新原生会话（session）所对应的会话的请求。

字段	类型	必填	说明
`schemaVersion`	`1`	是	请求结构的版本，始终为 `1`。
`operationId`	`string`	是	操作的标识。
`runtimeSessionId`	`string`	是	会话在 harness 中的标识。
`runtimeSessionKey?`	`string`	否	会话在 harness 中的 key。
`title?`	`string`	否	会话的标题。

RuntimeNativeConversationSyncResponse

TypeScript · 仅 TypeScript

同步时 Cloud 返回的会话。

字段	类型	必填	说明
`id`	`string`	是	会话的标识。
`participants`	`readonly string[]`	是	参与者的标识列表。
`metadata?`	`Readonly<Record<string, string>>`	否	会话的元数据。
`owner_identity_id?`	`string`	否	拥有该会话的身份。
`target_identity_id?`	`string`	否	该会话所对应的智能体的身份。
`target_kind?`	`string`	否	对象的种类。
`title?`	`string`	否	会话的标题。
`metadata_version`	`number`	是	元数据的版本，每次修改都会增大。
`history_generation`	`number`	是	会话历史的代数。
`last_activity_at?`	`string`	否	会话最后活跃的时间。
`state`	`"open" \| "closed"`	是	`open` 或 `closed`。
`closed_reason?`	`string`	否	会话被关闭的原因。
`single_shot?`	`boolean`	否	只接受一次提示的会话为 `true`。
`deadline_at?`	`string`	否	会话的截止时间。
`created_at`	`string`	是	会话创建的时间。
`closed_at?`	`string`	否	会话关闭的时间。

RuntimeOperationAppendRequest

Python · 仅 Python

向某个操作追加消息的请求。

字段	类型	必填	说明
`schemaVersion`	`Literal[1]`	是	请求结构的版本，始终为 `1`。
`type`	`str`	是	消息的类型。
`payload`	`Any`	是	消息内容。

RuntimeRealtimeToken

TypeScript 与 Python

实时连接令牌及其使用位置。

字段	类型	必填	说明
`token`	`string` / `str`	是	连接令牌。
`centrifugoUrl` / `centrifugo_url`	`string` / `str`	是	实时服务的 URL。
`channels`	`readonly string[]` / `tuple[str, ...]`	是	令牌允许订阅的频道。
`principalId` / `principal_id`	`string` / `str`	是	令牌所签发给的主体的标识。
`expiresAt` / `expires_at`	`number` / `int`	是	令牌的过期时间（Unix 时间戳）。聊天客户端把小于 10^12 的值按秒解读，更大的值按毫秒解读。

RuntimeRegistrationActiveResult

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

注册应答 active：租约已授予。

字段	类型	必填	说明
`status`	`"active"`	是	`active`。
`instanceId`	PlatformInstanceId	是	harness 所注册到的 Cloud 实例的标识。
`runtimeEpoch`	RuntimeEpoch	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`journalGeneration`	RuntimeRevision	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。
`leaseId`	`string`	是	运行时租约的标识。
`issuedAt`	RFC3339Timestamp	是	租约签发的时间（RFC 3339 时间戳）。
`leaseExpiresAt`	RFC3339Timestamp	是	租约过期的时间（RFC 3339 时间戳）。
`heartbeatIntervalMs`	`typeof RUNTIME_LEASE_HEARTBEAT_INTERVAL_MS`	是	租约必须续期的间隔，单位毫秒。
`runtimeLeaseCredential`	`string`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。

RuntimeRegistrationAuthorityLease

TypeScript · 仅 TypeScript

面向与租约绑定的数据通道的临时授权视图。凭据绝不能写入日志或日志存储（journal）。

继承: RuntimeActiveLease

字段	类型	必填	说明
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。

RuntimeRegistrationConfig

TypeScript · 仅 TypeScript

注册的配置：harness 是什么、能做什么。

字段	类型	必填	说明
`registrationId`	`string`	是	注册的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`contractRevision`	`string`	是	harness 所实现的运行时契约的修订号。
`runtimeMethods`	readonly RuntimeInvocationMethod[]	是	harness 能够处理的运行时方法。
`capabilities`	readonly RuntimeCapability[]	是	harness 提供的能力。
`manifestDigest`	RuntimeRegistrationHashPayload["manifestDigest"]	是	harness 清单的摘要。
`journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`journalGeneration`	`${bigint}`	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。
`instanceIdentityKeyId`	`string`	是	为证明签名的实例身份密钥的标识。
`targetInstanceId?`	`string`	否	该注册必须属于的 Cloud 实例。
`signIdentityProof`	`(message: Uint8Array) => Uint8Array`	是	密钥由宿主保管；对规范化的 Ed25519 证明字节签名。
`fencedRetry?`	BackoffPolicy \| false	否	`fenced` 应答是可恢复的：前任或控制面稳定期间，授权方可能会 fence 一个注册，所以协调器按此退避策略持续用同一意图重新注册。`false` 则恢复为终止性的 fence。默认：30 秒起翻倍到 5 分钟，不限次数。
`getMSConnectionStatus?`	(lease: RuntimeActiveLease) => MSConnectionStatus	否	返回心跳所携带的实时连接状态，可选。

RuntimeRegistrationFencedResult

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

注册应答 fenced：已有另一个注册生效。

字段	类型	必填	说明
`status`	`"fenced"`	是	`fenced`。
`activationId`	`string`	是	待激活流程的标识。
`runtimeEpoch`	RuntimeEpoch	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`activeRuntimeEpoch`	RuntimeEpoch	是	当前生效的注册的 epoch。

RuntimeRegistrationHashPayload

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

去掉签名字段后的注册请求。身份证明所签的就是它的哈希。

type RuntimeRegistrationHashPayload = Omit<RuntimeRegistrationRequest, "signaturePurpose" | "instanceIdentityKeyId" | "nonce" | "signedAt" | "payloadHash" | "signature">

RuntimeRegistrationIdentity

Python · 仅 Python

注册的持久身份。

字段	类型	必填	说明
`registration_id`	`str`	是	注册的标识。
`handler_identity`	`str`	是	处理方的身份。
`journal_store_id`	`str`	是	日志存储的标识。
`journal_generation`	`str`	是	日志存储的代数，十进制字符串。

RuntimeRegistrationPendingResult

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

注册应答 pending_activation：注册在等待前任交接。

字段	类型	必填	说明
`status`	`"pending_activation"`	是	`pending_activation`。
`activationId`	`string`	是	待激活流程的标识。
`runtimeEpoch`	RuntimeEpoch	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`journalGeneration`	RuntimeRevision	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。
`retryAfterMs`	`number`	是	重新注册前需要等待的时间，单位毫秒。

RuntimeRegistrationRequest

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

已签名的注册请求。

继承: RuntimeIdentityProof<"runtime.register">

字段	类型	必填	说明
`targetInstanceId?`	`string`	否	该注册必须属于的 Cloud 实例。
`registrationId`	`string`	是	注册的标识。
`handlerIdentity`	`string`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`contractRevision`	`string`	是	harness 所实现的运行时契约的修订号。
`manifestDigest`	Sha256HexDigest	是	harness 清单的摘要。
`runtimeRpcProtocolVersion`	typeof RUNTIME_RPC_PROTOCOL_VERSION	是	harness 所使用的运行时 RPC 协议的版本。
`runtimeMethods`	readonly RuntimeInvocationMethod[]	是	harness 能够处理的运行时方法。
`capabilities`	readonly RuntimeCapability[]	是	harness 提供的能力。
`journalStoreId`	`string`	是	harness 的持久化日志存储（journal store）的标识。
`journalGeneration`	RuntimeRevision	是	日志存储的代数（generation）。上一个租约过期或注册谱系变化时加一。

RuntimeRegistrationResult

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

注册的应答：pending_activation、active 或 fenced。

可选形态

#	类型
1	RuntimeRegistrationPendingResult
2	RuntimeRegistrationActiveResult
3	RuntimeRegistrationFencedResult

RuntimeRevision

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

修订号，十进制字符串。

type RuntimeRevision = DecimalUInt64

Sha256HexDigest

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

SHA-256 摘要，64 位小写十六进制字符。

type Sha256HexDigest = string

TerminalAgentAuthFrame

TypeScript 与 Python

harness 为认证而发给终端桥接的第一帧。

字段	类型	必填	说明
`type`	`'agent_auth'` / `Literal['agent_auth']`	是	始终为 `agent_auth`。
`instance_id`	`string` / `str`	是	Cloud 实例的标识。
`service`	`'terminal'` / `Literal['terminal']`	是	始终为 `terminal`。
`public_key`	`string` / `str`	是	标准 base64 的 Ed25519 公钥。
`timestamp`	`number` / `int`	是	Unix 时间（秒）。
`nonce`	`string` / `str`	是	一次性随机值。
`signature`	`string` / `str`	是	标准 base64 的 Ed25519 签名。
`runtimeLeaseCredential`	`string` / `str`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。
`handlerIdentity`	`string` / `str`	是	处理方身份，即完成注册并持有租约的 harness 进程。
`runtimeEpoch`	`string` / `str`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`leaseId`	`string` / `str`	是	运行时租约的标识。

TerminalAuthLease

TypeScript 与 Python

写入终端认证帧的租约信息。

字段	类型	必填	说明
`instanceId` / `instance_id`	`string` / `str`	是	harness 所注册到的 Cloud 实例的标识。
`leaseId` / `lease_id`	`string` / `str`	是	运行时租约的标识。
`runtimeEpoch` / `runtime_epoch`	`string` / `str`	是	运行时注册的 epoch（十进制字符串）。epoch 低于当前生效注册的注册会被 fence。
`runtimeLeaseCredential` / `runtime_lease_credential`	`string` / `str`	是	随租约签发的凭据，在租约调用中作为 Bearer 令牌发送。请当作机密对待，不要写入日志。
`handlerIdentity` / `handler_identity`	`string` / `str`	是	处理方身份，即完成注册并持有租约的 harness 进程。

TerminalBridgeClientOptions

TypeScript · 仅 TypeScript

终端桥接客户端的选项。

字段	类型	必填	说明
`bridgeUrl`	`string`	是	终端桥接的 URL。
`keys`	AgentKeyPair	是	harness 实例的 Ed25519 密钥对。
`lease`	TerminalAuthLease	是	为 harness 认证的租约。
`now?`	`() => number`	否	毫秒时钟，测试时可替换，默认 `Date.now`。
`nonce?`	`() => string`	否	nonce 生成函数，测试时可替换。
`authTimeoutMs?`	`number`	否	等待 `auth_ok` 的时间，单位毫秒，默认 10000。
`socketFactory?`	(url: string) => TerminalSocket	否	创建 WebSocket 的函数。测试时可替换，默认使用 `ws`。

VerifiedDecodedExecutionBoundary

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

签名已验证的边界断言。

字段	类型	必填	说明
`header`	CoreExecutionAuthorization["boundary"]["header"]	是	断言的 JWT 头。
`claims`	RuntimeExecutionBoundaryAssertionClaims	是	断言的声明。
`compactHash`	Sha256HexDigest	是	紧凑 JWT 的 SHA-256 摘要（64 位小写十六进制）。

VerifiedDecodedExecutionGrant

TypeScript · 仅 TypeScript · 来源: @beeos-ai/beeos-types

签名已验证的执行授权。

字段	类型	必填	说明
`header`	CoreExecutionAuthorization["grant"]["header"]	是	授权的 JWT 头。
`claims`	AnyRuntimeExecutionGrantClaims	是	授权的声明。
`compactHash`	Sha256HexDigest	是	紧凑 JWT 的 SHA-256 摘要（64 位小写十六进制）。

由 @beeos-ai/beeos-types 定义的类型

以下类型只被上面的结构间接引用，由 @beeos-ai/beeos-types 的 runtime 入口定义，本页不再展开：

ConversationRuntimeExecutionGrantClaims
ConversationRuntimeInvocationMethod
ConversationRuntimeInvocationResultMap
InstanceRuntimeExecutionGrantClaims
InstanceRuntimeInvocationMethod
InstanceRuntimeInvocationResultMap
InternalRuntimeInvocationMethod
RuntimeExecutionBoundaryAssertion
RuntimeExecutionGrantClaims
RuntimeExecutionGrantEnvelope
RuntimeIdentityKeyId
RuntimeInvocationValidationContextBase
ServiceRuntimeMethod

BeeOS Cloud返回文档首页