Canonical Bellona remote-control protocol package.
This package owns the typed contracts for the Phase 180 Remote Creative Control Plane. Gateway, host, MCP, adapters, tests, documentation, and future Control Room clients must import protocol contracts from here rather than defining parallel command or event shapes.
Current Scope#
180.C.03.01 established the Nx library boundary, package metadata, build,
lint, typecheck, and test targets.
180.C.03.02 adds the first protocol schema slice:
RemoteDeviceRemoteCapabilityRemoteAdapterRemotePermissionRemotePermissionScope
180.C.03.03 adds session coordination schemas:
RemoteSessionRemoteSessionStatusRemoteParticipantRemoteSurfaceRemoteSessionLifecycleEvent
180.C.03.04 adds command intake schemas:
RemoteCommandEnvelopeRemoteCommandPriorityRemoteCommandTimeoutClassRemoteCommandRiskClassRemoteCommandTarget
180.C.03.05 adds command completion and retry schemas:
RemoteCommandResultRemoteCommandProgressRemoteErrorCodeRemoteWarning- retry and idempotency metadata
180.C.03.06 adds audit, evidence, artifact, and approval schemas:
RemoteAuditEntryRemoteAuditEvidenceRemoteArtifactRemoteApprovalRequestRemoteApprovalDecision
180.C.03.07 adds stream source, descriptor, state, quality, health, and WebRTC
signaling metadata schemas:
RemoteStreamDescriptorRemoteStreamSourceRemoteStreamStateRemoteWebRtcSignalingMetadata
180.C.03.08 adds canonical command namespace constants:
REMOTE_COMMAND_NAMESPACEREMOTE_COMMAND_NAMESPACE_VALUESREMOTE_COMMAND_NAMESPACE_PATTERNREMOTE_COMMAND_NAMESPACE_PATTERNS
180.C.03.15 extends the namespace set with agent.* and state.* for dynamic
readiness and state commands.
180.C.03.09 adds generated contract artifacts and drift checks:
- JSON Schema bundle:
contracts/json-schema/bellona-remote-protocol.schema.json - OpenAPI 3.1 component bundle:
contracts/openapi/bellona-remote-protocol.openapi.json - Proto-ready manifest:
contracts/proto/bellona-remote-protocol.manifest.json - Generation target:
pnpm nx contracts:generate @bellona/remote-protocol - Drift check target:
pnpm nx contracts:check @bellona/remote-protocol
180.C.03.10 adds protocol version negotiation and compatibility policy
schemas:
RemoteProtocolCompatibilityPolicyRemoteProtocolCompatibilityRuleRemoteProtocolDeprecationPolicyRemoteProtocolPeerVersionRemoteProtocolVersionNegotiation- version comparison and selection helpers for host/gateway handshake tests
180.C.03.12 adds structured remediation to every protocol command error:
RemoteCommandErrorRemediationRemoteSuggestedNextCommandTemplatecreateRemoteCommandError()createRemoteCommandErrorRemediation()
Every RemoteCommandError must include human remediation text, an optional
machine-parseable suggested next command template, and an autoRetrySafe
boolean. The helper functions provide conservative defaults so downstream host,
gateway, and test harness error paths emit the same remediation shape.
180.C.03.13 adds stable actor and delegation-chain schemas:
RemoteActorRemoteActorKindRemoteActorChain
RemoteCommandEnvelope, RemoteAuditEntry, RemoteApprovalRequest, and
RemoteSessionLifecycleEvent now carry actor-chain data so command execution,
approval, audit, and timeline records can preserve the path from a human
operator through orchestration agents, specialist agents, and adapters.
180.C.03.14 adds rollback strategy metadata for mutating commands:
RemoteRollbackStrategyRemoteCommandMetadata
RemoteCommandEnvelope now rejects safe-mutation, destructive, and
privileged commands unless metadata.rollbackStrategy is one of undo_stack,
snapshot_restore, compensating_action, or manual_remediation_only.
Read-only commands may omit rollback metadata, but any supplied rollback
strategy must still match the enum.
180.C.03.15 adds dynamic agent-readiness and state-snapshot contracts:
RemoteAgentReadinessCommandNameRemoteStateSnapshotCommandNameRemoteAgentReadinessCommandArgumentsRemoteStateSnapshotCommandArgumentsRemoteAgentReadinessRemoteStateSnapshotRemoteModalDialogStateRemoteShaderCompileStateRemoteProjectRootStateRemoteRunningJobRemoteDynamicResourcePressure
agent.readiness and state.snapshot are read-only protocol commands that
report live host state alongside static RemoteCapability reports: modal
dialogs, shader compile activity, project-root write policy, running jobs, disk
pressure, and memory pressure.
180.C.03.16 adds dry-run plan contracts for high-risk commands:
RemoteDryRunPlanRemoteDryRunRequiredRiskClassRemoteDryRunPredictedChangeRemoteDryRunCostEstimateRemoteDryRunTimeEstimateRemoteDryRunReversibilityAssessment
Dry-run plans include predicted changes, token/compute/bandwidth/render/build
cost estimates, elapsed-time estimates, reversibility assessment, impact
summary, assumptions, and warnings. RemoteCommandEnvelope now requires
metadata.dryRunSupported: true and metadata.dryRunPlanId for destructive
and privileged commands. The shared policy evaluator also marks dry-run
required for every high-risk scope class from 180.C.07.06, including
project/file writes, desktop control, real browser profiles, arbitrary code,
shell, publishing, and financial actions.
180.C.09.03 adds the canonical read-only Blender scene-info contract:
RemoteBlenderSceneInfoCommandNameRemoteBlenderSceneInfoCommandArgumentsRemoteBlenderSceneInfoRemoteBlenderSceneRemoteBlenderCollectionRemoteBlenderObjectRemoteBlenderMaterialRemoteBlenderCameraRemoteBlenderLight
blender.scene.info reports scenes, collections, objects, materials, cameras,
lights, frame range, selected objects, render engine, active scene, active file
path, Blender version, and addon version. Host, gateway, MCP, and UI code must
import these contracts from @bellona/remote-protocol rather than defining
local Blender scene snapshots.
180.C.10.01 adds the canonical safe-mutation Blender primitive creation
contract:
RemoteBlenderCreatePrimitiveCommandNameRemoteBlenderCreatePrimitiveCommandArgumentsRemoteBlenderCreatePrimitiveCommandMetadataRemoteBlenderCreatePrimitiveCommandEnvelopeRemoteBlenderPrimitiveTypeRemoteBlenderCreatePrimitiveTransformRemoteBlenderCreatePrimitiveCollectionReferenceRemoteBlenderCreatePrimitiveMaterialReference
blender.object.create_primitive is constrained to safe-mutation, short
timeout class, at most 30 seconds, undo_stack rollback metadata, dry-run
metadata, and an explicit object name, primitive type, transform, optional
existing collection reference, and optional material reference. Later 180.C.10
tasks own undo checkpoint execution, host observe-only policy enforcement, scene
evidence capture, adapter mutation, and hardware smoke coverage.
180.C.17.02 adds the canonical safe-mutation Blender object mutation
contracts:
RemoteBlenderObjectDeleteCommandArgumentsRemoteBlenderObjectRenameCommandArgumentsRemoteBlenderObjectDuplicateCommandArgumentsRemoteBlenderObjectParentCommandArgumentsRemoteBlenderObjectSetTransformCommandArgumentsRemoteBlenderObjectSetVisibilityCommandArgumentsRemoteBlenderObjectMutationTransformRemoteBlenderObjectVisibilityStateRemoteBlenderUndoCheckpointRemoteBlenderSceneMutationEvidenceReferencesRemoteBlenderObjectMutationResult
blender.object.delete, blender.object.rename, blender.object.duplicate,
blender.object.parent, blender.object.set_transform, and
blender.object.set_visibility all share the same safe-mutation, short,
30-second, undo_stack metadata requirements. Result payloads must include the
mutated object identity, a valid undo checkpoint, and before/after scene
evidence references so host, gateway, MCP, and replay code all read the same
audit shape.
180.C.17.03 adds the canonical Blender collection management contracts:
RemoteBlenderCollectionCreateCommandArgumentsRemoteBlenderCollectionMoveObjectCommandArgumentsRemoteBlenderCollectionSetVisibilityCommandArgumentsRemoteBlenderCollectionSetRenderabilityCommandArgumentsRemoteBlenderCollectionHierarchyCommandArgumentsRemoteBlenderCollectionVisibilityStateRemoteBlenderCollectionRenderabilityStateRemoteBlenderCollectionMutationResultRemoteBlenderCollectionHierarchyResult
blender.collection.create, blender.collection.move_object,
blender.collection.set_visibility, and blender.collection.set_renderability
share the same safe-mutation, short, 30-second, undo_stack metadata
requirements as the object mutations and return the same before/after scene
evidence reference shape. The read-only blender.collection.hierarchy query
normalizes collection trees, parent-child relationships, object membership, and
render visibility into a single canonical result.
180.C.17.04 adds the canonical Blender material contracts:
RemoteBlenderMaterialCreatePrincipledCommandArgumentsRemoteBlenderMaterialAssignCommandArgumentsRemoteBlenderMaterialSetParameterCommandArgumentsRemoteBlenderMaterialBindTextureCommandArgumentsRemoteBlenderMaterialSemanticSearchCommandArgumentsRemoteBlenderMaterialParameterNameRemoteBlenderMaterialParameterValueRemoteBlenderMaterialTextureSlotRemoteBlenderMaterialTextureColorSpaceRemoteBlenderMaterialMutationResultRemoteBlenderMaterialSemanticSearchResult
blender.material.create_principled, blender.material.assign,
blender.material.set_parameter, and blender.material.bind_texture are
safe-mutation, short, 30-second, undo_stack commands and must return a
valid undo checkpoint plus before/after scene evidence references. The read-only
blender.material.semantic_search query returns deterministic scored matches,
matched terms/features, and assigned-object context so host, gateway, MCP, and
clients all consume the same material lookup shape.
180.C.18.01 adds the canonical Blender modifier-stack contracts:
RemoteBlenderModifierAddCommandArgumentsRemoteBlenderModifierConfigureCommandArgumentsRemoteBlenderModifierReorderCommandArgumentsRemoteBlenderModifierSetViewportEnabledCommandArgumentsRemoteBlenderModifierSetRenderEnabledCommandArgumentsRemoteBlenderModifierApplyCommandArgumentsRemoteBlenderModifierPropertyValueRemoteBlenderModifierStackEntryRemoteBlenderModifierStackSnapshotRemoteBlenderModifierMutationResult
blender.modifier.add, blender.modifier.configure,
blender.modifier.reorder, blender.modifier.set_viewport_enabled,
blender.modifier.set_render_enabled, and blender.modifier.apply are
safe-mutation, standard, 120-second, undo_stack commands. Every result
must include a valid undo checkpoint, before/after scene evidence references,
before/after modifier-stack snapshots, and a rollback note so host, gateway,
MCP, and replay code all consume the same modifier mutation shape.
180.C.18.02 adds the canonical Blender Geometry Nodes macro contracts:
RemoteBlenderGeometryNodesListMacrosCommandArgumentsRemoteBlenderGeometryNodesApplyMacroCommandArgumentsRemoteBlenderGeometryNodesMacroIdRemoteBlenderGeometryNodesMacroDescriptorRemoteBlenderGeometryNodesPlanSummaryRemoteBlenderGeometryNodesListMacrosResultRemoteBlenderGeometryNodesMacroMutationResult
blender.geometry_nodes.list_macros is a read-only, short, 15-second
catalog query for validated production macros.
blender.geometry_nodes.apply_macro is a safe-mutation, standard,
120-second, undo_stack command. Every macro mutation result must include a
valid undo checkpoint, before/after scene evidence references, before/after
modifier-stack snapshots, structured plan summaries, and a rollback note so
host, gateway, MCP, and replay code all consume the same Geometry Nodes
automation shape.
180.C.18.03 adds the canonical Blender mesh edit macro contracts:
RemoteBlenderMeshEditListMacrosCommandArgumentsRemoteBlenderMeshEditApplyMacroCommandArgumentsRemoteBlenderMeshEditMacroIdRemoteBlenderMeshSelectionDomainRemoteBlenderMeshEditMacroDescriptorRemoteBlenderMeshEditSelectionSnapshotRemoteBlenderMeshEditListMacrosResultRemoteBlenderMeshEditMacroMutationResult
blender.mesh_edit.list_macros is a read-only, short, 15-second catalog
query for validated edit-mode mesh macros. blender.mesh_edit.apply_macro is a
safe-mutation, standard, 120-second, undo_stack command. Every mesh-edit
mutation result must include a valid undo checkpoint, before/after scene
evidence references, before/after mesh-selection snapshots, selection-domain
precondition data, and a rollback note so host, gateway, MCP, and replay code
all consume the same advanced mesh-edit automation shape.
180.C.17.05 adds the canonical Blender asset import contracts:
RemoteBlenderAssetImportCommandArgumentsRemoteBlenderAssetImportCommandMetadataRemoteBlenderAssetImportFormatRemoteBlenderAssetImportSourceKindRemoteBlenderAssetImportProvenanceReferencesRemoteBlenderAssetImportResult
blender.asset.import is a safe-mutation, standard, 120-second,
undo_stack command that only accepts allowlisted GLB/GLTF, FBX, OBJ, USD,
USDZ, Alembic, image texture, and audio reference inputs inside the project
root. The result always carries a valid undo checkpoint, before/after scene
evidence references, a hashed source-file snapshot, and structured imported
object, collection, material, image, and sound identifiers so host, gateway,
MCP, and replay consumers read the same provenance-aware import shape.
180.C.17.06 adds the canonical Blender asset export contracts:
RemoteBlenderAssetExportCommandArgumentsRemoteBlenderAssetExportCommandMetadataRemoteBlenderAssetExportFormatRemoteBlenderAssetExportImageSequenceRemoteBlenderAssetExportedFileRemoteBlenderAssetExportTransferItemRemoteBlenderAssetExportTransferReferencesRemoteBlenderAssetExportHashVerificationRemoteBlenderAssetExportResult
blender.asset.export is a safe-mutation, long-running, 10-minute,
undo_stack command that only accepts allowlisted GLB/GLTF, FBX, OBJ, USD,
Alembic, image-sequence, and packaged .blend outputs inside the project root.
The result always carries before/after scene evidence references, verified
exported-file hashes, transfer-ready artifact metadata, and structured file
inventory records so host, gateway, MCP, and replay consumers share the same
export and artifact-registration shape.
180.C.17.07 adds the canonical Blender semantic selector contracts:
RemoteBlenderSemanticSelectorKindRemoteBlenderSemanticSelectorQueryCommandArgumentsRemoteBlenderSemanticSelectorQueryCommandMetadataRemoteBlenderSemanticSelectorQueryCommandTargetRemoteBlenderSemanticSelectorQueryCommandEnvelopeRemoteBlenderSemanticSelectorObjectMatchRemoteBlenderSemanticSelectorMaterialMatchRemoteBlenderSemanticSelectorQueryResult
blender.semantic_selector.query is a read-only, short, 15-second query
that resolves fixed selector presets rather than free-form search. The contract
currently covers all_emissive_objects, selected_character_rig,
large_static_props, objects_in_collection, and materials_missing_textures,
with deterministic ordering, collection resolution metadata, ranked match
records, and explicit object or material context so host, gateway, MCP, and
client code consume the same selector shape.
180.C.15.03 adds the canonical read-only Unreal project-info contract:
RemoteUnrealProjectInfoCommandNameRemoteUnrealProjectInfoCommandArgumentsRemoteUnrealReadonlyCommandMetadataRemoteUnrealProjectInfoCommandEnvelopeRemoteUnrealProjectInfoRemoteUnrealProjectPluginRemoteUnrealProjectModuleRemoteUnrealProjectBuildTarget
unreal.project.info reports project path/name/status, engine association and
version, plugins, modules, target platforms, mocked map/content-root summaries,
source-control status, build target metadata, config summary, and Bellona plugin
support. The command is constrained to read-only, standard timeout class,
localhost-only Remote Control assumptions, mutationAllowed: false, and
writesProjectFiles: false; host, gateway, MCP, and UI code must import these
contracts from @bellona/remote-protocol.
180.C.15.04 adds the canonical read-only Unreal world-query contract:
RemoteUnrealWorldQueryCommandNameRemoteUnrealWorldQueryCommandArgumentsRemoteUnrealWorldQueryCommandEnvelopeRemoteUnrealWorldQueryRemoteUnrealWorldSummaryRemoteUnrealLevelSummaryRemoteUnrealActorSummaryRemoteUnrealWorldEditorStateRemoteUnrealWorldQueryBlocker
unreal.world.query reports a bounded map/world summary, persistent and
streaming level summaries, actor class counts, actor samples, optional component
samples, selected actors, shader compile state, editor busy state, and
structured blockers for unavailable project/plugin/editor conditions. The
command shares the Unreal read-only metadata requirements and must not mutate
map, level, actor, selection, PIE, or project state.
180.C.15.07 adds the first canonical Unreal safe-mutation contract:
RemoteUnrealActorSpawnCommandNameRemoteUnrealActorSpawnCommandArgumentsRemoteUnrealActorSpawnCommandMetadataRemoteUnrealActorSpawnCommandEnvelopeRemoteUnrealActorSpawnResultRemoteUnrealActorReferenceRemoteUnrealActorSpawnTransactionRemoteUnrealActorSpawnEvidenceReferences
unreal.actor.spawn is constrained to safe-mutation, short timeout class,
at most 30 seconds, localhost-only Remote Control assumptions, undo_stack
rollback metadata, dry-run metadata, an editor transaction requirement, and
writesProjectFiles: false. Results must include the spawned actor summary, an
explicit object reference, committed transaction/undo checkpoint metadata, and a
screenshot/evidence placeholder until live Unreal plugin screenshot capture is
covered by hardware smoke testing.
180.C.11.03 adds canonical Browser CDP MVP command contracts:
RemoteBrowserLaunchManagedCommandArgumentsRemoteBrowserNavigateCommandArgumentsRemoteBrowserSnapshotCommandArgumentsRemoteBrowserScreenshotCommandArgumentsRemoteBrowserCloseCommandArgumentsRemoteBrowserCompensatingActionRemoteBrowserSafeMutationCommandMetadataRemoteBrowserReadonlyCommandMetadataRemoteBrowserManagedSession
browser.launch_managed and browser.close are constrained to safe-mutation,
short timeout class, isolated profiles, localhost-only CDP, and explicit
rollback metadata. 180.C.11.11 adds browser compensating-action descriptors:
browser.launch_managed points at a browser.close cleanup action with
rollbackStrategy: "compensating_action", while browser.close documents a
manual_remediation_only relaunch path because the isolated profile is removed
by design. Future mutating browser commands such as form submit, download, or
account mutation must add their own back-navigation, cancel, delete-download, or
revoke-form compensating actions before they become routable. The
operator-facing framework is documented in
docs/domains/bellona/extras/remote-control/browser-compensating-actions.md.
180.C.11.12 makes compensating action ids mandatory for mutating browser
envelopes at both browser-specific schema validation and generic gateway/host
command-envelope validation. browser.navigate, browser.snapshot, and
browser.screenshot are read-only commands for isolated browser sessions. Every
browser command schema rejects real profile access and non-localhost CDP
assumptions; later 180.C.11 tasks own host launch, Playwright execution,
screenshot artifacts, and timeline routing.
180.C.13.11 adds desktop fallback compensating-action contracts:
RemoteDesktopCompensatingActionRemoteDesktopCompensatingActionKindRemoteDesktopCompensatingActionVerificationRemoteDesktopMutatingCommandName
180.C.13.12 adds the keyboard-layout-aware desktop.type contract:
RemoteDesktopTypeCommandArgumentsRemoteDesktopTypeCommandMetadataRemoteDesktopTypeCommandEnvelopeRemoteDesktopKeyboardLayoutReport
180.C.13.13 adds stable display identity contracts:
RemoteDesktopDisplayRemoteDesktopDisplaySelectorRemoteDesktopDisplayListCommandArgumentsRemoteDesktopDisplayListCommandEnvelopeRemoteDesktopDisplayListResult
Display records carry a UUID-backed stable id, current direct display id,
current display index, name, bounds, pixel size, scale factor, primary/active
state, built-in/mirrored flags, and rotation. Window display metadata and
display-targeting commands can therefore store desktop-display:<uuid> instead
of relying on primary/secondary labels or the current display arrangement.
180.C.13.14 adds redaction-aware clipboard capture contracts:
RemoteDesktopClipboardCaptureCommandArgumentsRemoteDesktopClipboardCaptureCommandEnvelopeRemoteDesktopClipboardCaptureRedactionPatternRemoteDesktopClipboardCaptureResult
desktop.clipboard.capture is read-only and records text sourced from the
system clipboard, not OCR. Arguments declare byte/character limits, whether the
operator copied visible screen text, whether redacted text may be returned
inline, and which builtin or custom redaction hook should run. Results carry the
redacted text artifact/evidence, pasteboard change count and type metadata,
raw/redacted hashes, redaction pattern labels, and optional inline redacted text
for session-note insertion.
desktop.window.focus, desktop.click, desktop.type, and
desktop.emergency_stop are safe-mutation desktop commands with protocol-owned
compensating_action_id metadata and
rollbackStrategy: "manual_remediation_only". Desktop fallback does not claim
native undo for pointer or keyboard input. Current remediation paths are
explicit refocus, click evidence review plus click-back only for
operator-confirmed idempotent targets, typed-text undo/remediation through the
target application's reviewed path, and interrupted-session review after
emergency stop. desktop.type records active keyboard layout family,
input-source kind, layout-data availability, IME/composition state, physical
keyboard shape, and emission mode so clients do not assume US QWERTY. Generic
command-envelope validation rejects safe-mutation desktop commands without a
catalog entry, without the required compensating_action_id, or with a
mismatched rollback strategy. The operator-facing framework is documented in
docs/domains/bellona/extras/remote-control/desktop-compensating-actions.md.
180.C.07.06 adds the shared command permission policy evaluator:
REMOTE_PERMISSION_SCOPE_VALUESnow includes project-write, arbitrary-code, shell, publishing, and financial-action scopes in addition to the existing observe-only, desktop-control, browser-profile, and destructive scopes.getRemoteCommandRequiredPermissionScopes()infers required scopes from a command envelope and the advertised capability scope list.evaluateRemoteCommandPolicy()denies unadvertised commands, blocked devices/adapters/capabilities, missing/denied/expired permissions, and returnsrequires-approvalfor command or scope decisions that must be approved before dispatch.RemoteCommandPolicyEvaluationis exported and included in generated contract artifacts.
Schema Ownership Closure#
180.C.03.11 closes the Phase 180 remote-protocol package stage. This package
is the schema owner for device, session, command, result, audit, stream,
namespace, generated-contract, and version-negotiation contracts added in
180.C.03.
Closure verification for this stage is:
pnpm nx contracts:check @bellona/remote-protocolpnpm nx build @bellona/remote-protocolpnpm nx typecheck @bellona/remote-protocolpnpm nx lint @bellona/remote-protocolpnpm nx test @bellona/remote-protocol
Guardrails#
- Do not add gateway, host, MCP, adapter, or Control Room authority here.
- Do not define implementation-specific transport behavior in protocol types.
- Do not duplicate protocol contracts in downstream packages.