BEEOS CLOUD / DEVELOPER REFERENCE

Receiving runtime methods

Read, renew and acknowledge deliveries, append results, and use the lease-authenticated HTTP plane.

Cloud queues runtime method calls (such as session/prompt) for the harness as deliveries. The delivery consumer reads them under the current lease, keeps them alive while your handler runs, and lets you acknowledge or append results. Appends are never blindly replayed: an uncertain outcome is reconciled through operation history.

NodeRuntimeDeliveryPort

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

Default delivery port. It reads runtime-method deliveries from Cloud over HTTP using the current lease credential, runs the claim lifecycle, and exposes consume() to start a consumer. In Python the same role is played by RuntimeDeliveryPort.

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

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`origin`	RuntimeDeliveryOriginPort	yes		Supplies the origin (scheme and host) of the Cloud message service.
`authority`	RuntimeDeliveryAuthorityPort	yes		Supplies the current runtime lease; usually the registration coordinator adapted to `RuntimeDeliveryAuthorityPort`.

Python · Constructor

Parameter	Type	Required	Default	Description
`service_origin`	`str \| Callable[[], str \| Awaitable[str]]`	yes		Origin of the Cloud message service, or a function (sync or async) that returns it.
`authority`	`Any`	yes		Supplies the current runtime lease; usually the registration coordinator adapted to `RuntimeDeliveryAuthorityPort`.
`http_client`	`httpx.AsyncClient \| None`	no	`None`	Optional `httpx.AsyncClient` to send requests with.
`scoped_delivery_key`	`str \| None`	no	`None`	Delivery key sent as `X-Runtime-Delivery-Key`; required by session-model projection and cron delivery.

consume

Creates a consumer that reads, renews and hands out deliveries. Call start() on it to begin; the handler must acknowledge each delivery.

consume(options: RuntimeDeliveryConsumeOptions): RuntimeDeliveryConsumer

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`options`	RuntimeDeliveryConsumeOptions	yes		Handler, error callbacks and tuning values of the consumer.

Returns RuntimeDeliveryConsumer

Python · Parameters

Parameter	Type	Required	Default	Description
`on_delivery`	`Callable[..., Any]`	yes		Called with each `RuntimeMethodDelivery` and the consumer. May be sync or async; it must acknowledge the delivery when done.
`on_error`	`Callable[[BaseException], None] \| None`	no	`None`	Called with errors from the read, renew and handler steps; they are otherwise ignored.
`max_count`	`int`	no	`32`	Maximum number of deliveries to return in one read.
`block_ms`	`int`	no	`5000`	How long the server may hold the read open while waiting for deliveries, in milliseconds.
`idle_delay_s`	`float`	no	`0.5`	Pause in seconds when there is no lease or a read returned nothing to handle. Defaults to 0.5.
`renew_interval_s`	`float`	no	`20.0`	Interval in seconds between renewals of the deliveries in flight. Defaults to 20.

Returns RuntimeDeliveryConsumer

startConversationRun

TypeScript only

Sends the start request of a conversation run with the current lease and returns the raw Response. The caller is responsible for signed operation admission.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	ConversationRuntimeBoundaryStartRequest	yes		The signed request that starts the conversation run, including the lease that must match the current one.

Returns Promise<Response>

finishConversationRun

TypeScript only

Sends the finish request of a conversation run with the current lease and returns the raw Response.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	ConversationRuntimeBoundaryFinishRequest	yes		The signed request that finishes the conversation run, including the lease that must match the current one.

Returns Promise<Response>

current_lease

Python only

Returns the current lease from the authority, or None.

def current_lease() -> Any

Python · Parameters

No parameters.

Returns Any

read

Python only

Reads up to max_count deliveries, waiting up to block_ms for the first one. Raises HarnessProtocolError for an invalid answer.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`max_count`	`int`	yes		Maximum number of deliveries to return in one read.
`block_ms`	`int`	yes		How long the server may hold the read open while waiting for deliveries, in milliseconds.

Returns list[RuntimeMethodDelivery]

renew

Python only

Renews the given deliveries and returns the answer, whose notPending list holds deliveries that are no longer pending.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`delivery_ids`	`list[str]`	yes		Identifiers of the deliveries.

Returns dict[str, Any]

acknowledge

Python only

Acknowledges the deliveries so they are not delivered again. Raises HarnessProtocolError unless exactly the given ids are acknowledged.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`delivery_ids`	`list[str]`	yes		Identifiers of the deliveries.

Returns Any

history

Python only

Returns the stored history of an operation: {"status": "not_found"}, {"status": "expired"}, or {"status": "found", "snapshot": ...}.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`operation_id`	`str`	yes		Identifier of the operation.

Returns dict[str, Any]

append

Python only

Appends a message to an operation and returns the answer. The call is never retried automatically, so an uncertain result must be reconciled with history.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`operation_id`	`str`	yes		Identifier of the operation.
`type`	`str`	yes		Type of the appended message.
`payload`	`Any`	yes		Payload of the appended message.
`execution_grant`	`str \| None`	no	`None`	Per-operation execution grant, sent as `X-BeeOS-Execution-Grant`.

Returns Any

history_boundary

Python only

Runs a history-boundary action for a conversation. fields use snake_case names that are mapped to the wire names.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`conversation_id`	`str`	yes		Identifier of the conversation.
`action`	`str`	yes		History boundary action: `prepare`, `resetting`, `reset_done`, `commit`, `abort` or `reconcile`.
`body`	`Mapping[str, Any] \| None`	no	`None`	Request body of the call, as JSON-compatible data.
`**fields`	`Any`	yes		Extra body fields: `operation_id`, `request_message_id`, `request_hash`, `boundary_token`, `effect_receipt`, `run_convergence` or `active_run_registration_id`. Any other name raises `HarnessProtocolError`.

Returns Any

project_session_model

Python only

Publishes the session model of a conversation. Requires a scoped_delivery_key; the call may be retried.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`conversation_id`	`str`	yes		Identifier of the conversation.
`body`	`Any`	yes		Request body of the call, as JSON-compatible data.

Returns Any

deliver_cron

Python only

Delivers a scheduled-task result into a conversation. Requires a scoped_delivery_key; the call may be retried.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`conversation_id`	`str`	yes		Identifier of the conversation.
`body`	`Any`	yes		Request body of the call, as JSON-compatible data.

Returns Any

RuntimeClaimClient

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

Calls of the invocation claim lifecycle: claim the next or an exact operation, renew a claim, and release it.

class RuntimeClaimClient
new RuntimeClaimClient(readonly http: RuntimeLeaseHttp)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`http`	RuntimeLeaseHttp	yes		Lease-authenticated HTTP client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`http`	RuntimeLeaseHttp	yes		Lease-authenticated HTTP client that sends the requests.

claimNext / claim_next

Claims the next pending operation. The returned status is claimed, empty or fenced.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	RuntimeClaimNextRequest	yes		Request body of the call, as JSON-compatible data.

Returns Promise<{ status: string }>

Python · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	`dict[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns dict[str, Any]

claimExact / claim_exact

Claims one specific operation. The returned status is claimed, already_claimed, fenced, epoch_handoff_required or terminal.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	RuntimeClaimExactRequest	yes		Request body of the call, as JSON-compatible data.

Returns Promise<{ status: string }>

Python · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	`dict[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns dict[str, Any]

renewClaim / renew_claim

Renews a claim. The returned status is renewed, fenced, expired or terminal.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	RuntimeClaimRenewRequest	yes		Request body of the call, as JSON-compatible data.

Returns Promise<{ status: string }>

Python · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	`dict[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns dict[str, Any]

releaseClaim / release_claim

Releases a claim with a reason. Throws HarnessProtocolError unless Cloud answers 204.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	RuntimeClaimReleaseRequest	yes		Request body of the call, as JSON-compatible data.

Returns Promise<void>

Python · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`body`	`dict[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns None

RuntimeDeliveryAuthorityPort

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

Source of the current lease for the delivery port. Adapt your registration coordinator to it.

interface RuntimeDeliveryAuthorityPort

currentLease

Returns the current lease with its credential, or null when there is none.

currentLease(): RuntimeDeliveryAuthorityLease | null

TypeScript · Parameters

No parameters.

Returns RuntimeDeliveryAuthorityLease | null

subscribeAuthority

Optional. Registers a listener that is called when the lease changes, so in-flight handlers can be cancelled. Returns a function that removes the listener.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`listener`	`() => void`	yes		Callback invoked when the lease changes.

Returns () => void

RuntimeDeliveryConsumer

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

A running consumer. It reads and renews deliveries and calls your handler, which reads the operation history, appends messages and acknowledges deliveries through the methods below.

interface RuntimeDeliveryConsumer

Python · Constructor

Parameter	Type	Required	Description
`port`	RuntimeDeliveryPort	yes	The delivery port that performs the requests.
`on_delivery`	`Callable[..., Any]`	yes	Called with each `RuntimeMethodDelivery` and the consumer. May be sync or async.
`on_error`	`Callable[[BaseException], None] \| None`	yes	Called with errors from the read, renew and handler steps.
`max_count`	`int`	yes	Maximum number of deliveries to return in one read.
`block_ms`	`int`	yes	How long the server may hold the read open while waiting for deliveries, in milliseconds.
`idle_delay_s`	`float`	yes	Pause in seconds when there is no lease or nothing to handle.
`renew_interval_s`	`float`	yes	Interval in seconds between renewals of the deliveries in flight.

start

Starts the read and renew loops. Calling it again while running does nothing.

start(): void

TypeScript · Parameters

No parameters.

Returns void

Python · Parameters

No parameters.

Returns None

stop

Stops reading and renewing and resolves when the loop has ended. In TypeScript, running handlers are cancelled through their abort signal.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`signal`	`AbortSignal`	no		Aborting this signal cancels the call.

Returns Promise<void>

Python · Parameters

No parameters.

Returns None

history

Returns the stored history of an operation, using the current lease. Throws when there is no valid lease.

history(operationId: string): Promise<RuntimeDeliveryHistory>

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`operationId`	`string`	yes		Identifier of the operation.

Returns Promise<RuntimeDeliveryHistory>

Python · Parameters

Parameter	Type	Required	Default	Description
`operation_id`	`str`	yes		Identifier of the operation.

Returns dict[str, Any]

append

Appends a message to an operation, using the current lease, and returns a receipt. The call is not retried automatically; when the receipt is outcome_unknown, reconcile with history.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`operationId`	`string`	yes	Identifier of the operation.
`type`	`string`	yes	Type of the appended message.
`payload`	JsonValue	yes	Payload of the appended message.
`executionGrant`	`string`	no	Per-operation execution grant, sent as `X-BeeOS-Execution-Grant`.

Returns Promise<RuntimeDeliveryAppendReceipt>

Python · Parameters

Parameter	Type	Required	Default	Description
`operation_id`	`str`	yes		Identifier of the operation.
`type`	`str`	yes		Type of the appended message.
`payload`	`Any`	yes		Payload of the appended message.
`execution_grant`	`str \| None`	no	`None`	Per-operation execution grant, sent as `X-BeeOS-Execution-Grant`.

Returns Any

acknowledge

Acknowledges deliveries so they are not delivered again. Call it when the handler is done.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`deliveryIds`	`readonly string[]`	yes		Identifiers of the deliveries.

Returns Promise<void>

Python · Parameters

Parameter	Type	Required	Default	Description
`delivery_ids`	`list[str]`	yes		Identifiers of the deliveries.

Returns Any

history_boundary

Python only

Runs a history-boundary action for a conversation through the port.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`conversation_id`	`str`	yes		Identifier of the conversation.
`action`	`str`	yes		History boundary action: `prepare`, `resetting`, `reset_done`, `commit`, `abort` or `reconcile`.
`body`	`Mapping[str, Any] \| None`	no	`None`	Request body of the call, as JSON-compatible data.
`**fields`	`Any`	yes		Extra body fields in snake_case, as accepted by `RuntimeDeliveryPort.history_boundary`.

Returns Any

RuntimeDeliveryOriginPort

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

Source of the Cloud message service origin.

interface RuntimeDeliveryOriginPort

serviceOrigin

Resolves the origin (scheme and host) of the message service.

serviceOrigin(): Promise<string>

TypeScript · Parameters

No parameters.

Returns Promise<string>

RuntimeDeliveryPort

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

Entry point of the delivery transport: creates consumers.

interface RuntimeDeliveryPort

consume

Creates a consumer; call start() on it to begin.

consume(options: RuntimeDeliveryConsumeOptions): RuntimeDeliveryConsumer

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`options`	RuntimeDeliveryConsumeOptions	yes		Handler, error callbacks and tuning values of the consumer.

Returns RuntimeDeliveryConsumer

RuntimeLeaseHttp

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

HTTP client for the Cloud data plane. It attaches the lease credential as Authorization: Bearer, only to one fixed origin, and refuses redirects and answers from another origin.

class RuntimeLeaseHttp
new RuntimeLeaseHttp(readonly options: RuntimeLeaseHttpOptions)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`options`	RuntimeLeaseHttpOptions	yes		`origin` is the only origin the credential is sent to; `retry` is the default retry policy (none by default); `fetch` replaces the global `fetch`.

Python · Constructor

Parameter	Type	Required	Default	Description
`origin`	`str`	yes		The only origin the credential may be sent to. It must be `http` or `https` without user information.
`client`	`httpx.AsyncClient \| None`	no	`None`	Optional `httpx.AsyncClient` to send requests with; a temporary client is used when omitted.
`timeout`	`float`	no	`30.0`	Timeout in seconds.
`retry`	BackoffPolicy \| None	no	`None`	Default retry policy for calls; `None` means no automatic retry.

Properties

Name	Type	Description
`readonly origin`	`URL`	The fixed origin the credential is sent to.

fetch

Sends a request with the lease credential. retry: true marks the call idempotent; by default a call is never replayed, so the caller reconciles an uncertain append or acknowledgement. Throws when the target is on another origin.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`target`	`string \| URL`	yes		Path starting with `/`, or an absolute URL on the fixed origin.
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`init`	`RequestInit`	no	`{}`	Standard `fetch` options (method, body, headers, signal).
`resilience`	{ retry?: boolean \| BackoffPolicy }	no	`{}`	`retry`: `true` for the transient policy, a `BackoffPolicy`, or `false` for none. Retried statuses are 502, 503 and 504.

Returns Promise<Response>

Python · Parameters

Parameter	Type	Required	Default	Description
`method`	`str`	yes		HTTP method.
`target`	`str`	yes		Path starting with `/`, or an absolute URL on the fixed origin.
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`json_body`	`Any`	no	`None`	JSON body to send.
`content`	`bytes \| None`	no	`None`	Raw bytes to send as the body.
`headers`	`Mapping[str, str] \| None`	no	`None`	Additional request headers.
`timeout`	`float \| None`	no	`None`	Timeout in seconds.
`retry`	bool \| BackoffPolicy	no	`False`	`True` for the transient policy, a `BackoffPolicy`, or `False` (default) for no retry.

Returns httpx.Response

postJson

TypeScript only

Sends a JSON POST and returns the raw Response, so the caller maps domain errors itself.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`path`	`string`	yes	Request path.
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`resilience`	{ retry?: boolean \| BackoffPolicy }	no	Retry setting as for `fetch`: `true`, a `BackoffPolicy`, or `false`.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<Response>

RuntimeMessagePlane

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

Calls to one Cloud message service origin: read, renew and acknowledge deliveries, read operation history, append messages, and run conversation-level actions.

class RuntimeMessagePlane
new RuntimeMessagePlane(readonly http: RuntimeLeaseHttp)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`http`	RuntimeLeaseHttp	yes		Lease-authenticated HTTP client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`http`	RuntimeLeaseHttp	yes		Lease-authenticated HTTP client that sends the requests.

readDeliveries / read_deliveries

Reads deliveries, holding the request open for up to blockMs. Returns the decoded answer.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`input`	`{ maxCount: number; blockMs: number }`	yes	`maxCount` is the most deliveries to return; `blockMs` is how long the server may wait for one.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`max_count`	`int`	yes	Maximum number of deliveries to return in one read.
`block_ms`	`int`	yes	How long the server may hold the read open while waiting for deliveries, in milliseconds.

Returns Any

renewDeliveries / renew_deliveries

Renews deliveries that are still being handled. Returns the decoded answer.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`deliveryIds`	`readonly string[]`	yes	Identifiers of the deliveries.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`delivery_ids`	`list[str]`	yes		Identifiers of the deliveries.

Returns Any

ackDeliveries / ack_deliveries

Acknowledges deliveries. Returns the decoded answer.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`deliveryIds`	`readonly string[]`	yes	Identifiers of the deliveries.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`delivery_ids`	`list[str]`	yes		Identifiers of the deliveries.

Returns Any

operationHistory / operation_history

Fetches the stored history of an operation.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operationId`	`string`	yes	Identifier of the operation.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Default	Description
`credential`	RuntimeLeaseCredential	yes		Runtime lease credential that authorises the call.
`operation_id`	`str`	yes		Identifier of the operation.

Returns Any

appendOperationMessage / append_operation_message

Appends a message to an operation. It is not retried automatically.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operationId`	`string`	yes	Identifier of the operation.
`body`	`{ type: string; payload: unknown }`	yes	Request body of the call, as JSON-compatible data.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operation_id`	`str`	yes	Identifier of the operation.
`type`	`str`	yes	Type of the appended message.
`payload`	`Any`	yes	Payload of the appended message.

Returns Any

historyBoundary / history_boundary

Runs a history-boundary action for a conversation; the call may be retried.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`conversationId`	`string`	yes	Identifier of the conversation.
`action`	HistoryBoundaryAction	yes	History boundary action: `prepare`, `resetting`, `reset_done`, `commit`, `abort` or `reconcile`.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`conversation_id`	`str`	yes	Identifier of the conversation.
`action`	`str`	yes	History boundary action: `prepare`, `resetting`, `reset_done`, `commit`, `abort` or `reconcile`.
`body`	`Any`	yes	Request body of the call, as JSON-compatible data.

Returns Any

projectSessionModel / project_session_model

Publishes the session model of a conversation. The credential must carry a scopedDeliveryKey; the call may be retried.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`conversationId`	`string`	yes	Identifier of the conversation.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`conversation_id`	`str`	yes	Identifier of the conversation.
`body`	`Any`	yes	Request body of the call, as JSON-compatible data.

Returns Any

deliverCron / deliver_cron

Delivers a scheduled-task result into a conversation. The credential must carry a scopedDeliveryKey; the call may be retried.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`conversationId`	`string`	yes	Identifier of the conversation.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`conversation_id`	`str`	yes	Identifier of the conversation.
`body`	`Any`	yes	Request body of the call, as JSON-compatible data.

Returns Any

RuntimeOperationFiles

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

File calls for an operation: resolve its input files, and presign and confirm its output files. These go to the gateway origin, not the message service.

class RuntimeOperationFiles
new RuntimeOperationFiles(readonly http: RuntimeLeaseHttp)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`http`	RuntimeLeaseHttp	yes		Lease-authenticated HTTP client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`http`	RuntimeLeaseHttp	yes		Lease-authenticated HTTP client that sends the requests.

resolveInput / resolve_input

Resolves the input files of an operation into download locations. The call may be retried.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operationId`	`string`	yes	Identifier of the operation.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operation_id`	`str`	yes	Identifier of the operation.
`body`	`Any`	yes	Request body of the call, as JSON-compatible data.

Returns Any

presignOutput / presign_output

Requests presigned upload locations for the output files of an operation. The call may be retried.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operationId`	`string`	yes	Identifier of the operation.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operation_id`	`str`	yes	Identifier of the operation.
`body`	`Any`	yes	Request body of the call, as JSON-compatible data.

Returns Any

confirmOutput / confirm_output

Confirms that the output files of an operation were uploaded. The call may be retried.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operationId`	`string`	yes	Identifier of the operation.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`signal`	`AbortSignal`	no	Aborting this signal cancels the call.

Returns Promise<unknown>

Python · Parameters

Parameter	Type	Required	Description
`credential`	RuntimeLeaseCredential	yes	Runtime lease credential that authorises the call.
`operation_id`	`str`	yes	Identifier of the operation.
`body`	`Any`	yes	Request body of the call, as JSON-compatible data.

Returns Any

create_runtime_delivery_port

Python beeos_cloud_harness_sdk.runtime_delivery_port · Python only

Creates a 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 · Parameters

Parameter	Type	Required	Default	Description
`service_origin`	`str \| Callable[[], str \| Awaitable[str]]`	yes		Origin of the Cloud message service, or a function (sync or async) that returns it.
`authority`	`Any`	yes		Object that provides the current lease, either through `current_lease()` or `currentLease()` or as an attribute.
`http_client`	`httpx.AsyncClient \| None`	no	`None`	Optional `httpx.AsyncClient` to send requests with.
`scoped_delivery_key`	`str \| None`	no	`None`	Delivery key sent as `X-Runtime-Delivery-Key`; required by session-model projection and cron delivery.

Returns RuntimeDeliveryPort

putPresignedUpload

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

Uploads bytes to a presigned URL with PUT. The lease credential is not sent.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	`{ url: string; allowedOrigin: string; body: Uint8Array; method?: string; requiredHeaders?: Record<string, string>; signal?: AbortSignal; fetchImpl?: typeof fetch; }`	yes		`url` and `allowedOrigin` (the upload must go to that https origin), `body` bytes, optional `method` (default `PUT`), `requiredHeaders`, `signal` and `fetchImpl`.

Returns Promise<Response>

Python · Parameters

Parameter	Type	Required	Default	Description
`url`	`str`	yes		The presigned upload URL. It must use https and carry no user information.
`allowed_origin`	`str`	yes		The only origin the upload may go to.
`body`	`bytes`	yes		Request body of the call, as JSON-compatible data.
`method`	`str`	no	`'PUT'`	HTTP method.
`required_headers`	`Mapping[str, str] \| None`	no	`None`	Headers that the presigned URL requires.
`client`	`httpx.AsyncClient \| None`	no	`None`	Optional `httpx.AsyncClient` to send requests with; a temporary client is used when omitted.

Returns httpx.Response

CLOUD_GATEWAY_RUNTIME_ROUTES

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

Builds the paths of the lease-authenticated file routes on the gateway.

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

Entries

Name	Type	Description
`outputFiles`	`(operationId: string, stage: "presign" \| "confirm") => string`	Path to presign or confirm the output files of an operation.
`inputFilesResolve`	`(operationId: string) => string`	Path to resolve the input files of an operation.

CLOUD_MESSAGE_ROUTES

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

Paths of the lease-authenticated message service routes; use them with 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; }>

Entries

Name	Type	Description
`deliveriesRead`	`string`	Path to read deliveries.
`deliveriesRenew`	`string`	Path to renew deliveries.
`deliveriesAck`	`string`	Path to acknowledge deliveries.
`conversations`	`string`	Path to synchronise conversations.
`operationHistory`	`(operationId: string) => string`	Path to read the history of an operation.
`operationMessages`	`(operationId: string) => string`	Path to append a message to an operation.
`historyBoundary`	(conversationId: string, action: HistoryBoundaryAction) => string	Path of a history-boundary action of a conversation.
`metadataModel`	`(conversationId: string) => string`	Path to publish the session model of a conversation.
`cronDelivery`	`(conversationId: string) => string`	Path to deliver a scheduled-task result into a conversation.
`claimNext`	`string`	Path to claim the next pending operation.
`claimExact`	`(operationId: string) => string`	Path to claim a specific operation.
`claimRenew`	`(operationId: string) => string`	Path to renew the claim of an operation.
`claimRelease`	`(operationId: string) => string`	Path to release the claim of an operation.

HarnessProtocolError

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

Raised when Cloud answers with an error status or an answer that does not have the expected shape, or when a call is refused before it is sent (for example a missing delivery key).

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

TypeScript · Constructor

Parameter	Type	Required	Description
`message`	`string`	yes	Error message.
`status`	`number`	no	HTTP status code, when the error comes from an answer.
`body`	`string`	no	Request body of the call, as JSON-compatible data.

Python · Constructor

Parameter	Type	Required	Default	Description
`message`	`str`	yes		Error message.
`status`	`int \| None`	no	`None`	HTTP status code, when the error comes from an answer.
`body`	`str \| None`	no	`None`	Request body of the call, as JSON-compatible data.

Properties

Name	Type	Description
`readonly status?`	`number`	HTTP status code, when the error comes from an answer.
`readonly body?`	`string`	Response body text, when the error comes from an answer.

Errors and exceptions

Error types that this module defines. The description of each method says when it raises one.

Errors	Language	Description
HarnessProtocolError	TypeScript, Python	Raised when Cloud answers with an error status or an answer that does not have the expected shape, or when a call is refused before it is sent (for example a missing delivery key).

BeeOS CloudBack to documentation