Eve library

@bellona/remote-protocol

Other

Revision 1

On this page

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:

  • RemoteDevice
  • RemoteCapability
  • RemoteAdapter
  • RemotePermission
  • RemotePermissionScope

180.C.03.03 adds session coordination schemas:

  • RemoteSession
  • RemoteSessionStatus
  • RemoteParticipant
  • RemoteSurface
  • RemoteSessionLifecycleEvent

180.C.03.04 adds command intake schemas:

  • RemoteCommandEnvelope
  • RemoteCommandPriority
  • RemoteCommandTimeoutClass
  • RemoteCommandRiskClass
  • RemoteCommandTarget

180.C.03.05 adds command completion and retry schemas:

  • RemoteCommandResult
  • RemoteCommandProgress
  • RemoteErrorCode
  • RemoteWarning
  • retry and idempotency metadata

180.C.03.06 adds audit, evidence, artifact, and approval schemas:

  • RemoteAuditEntry
  • RemoteAuditEvidence
  • RemoteArtifact
  • RemoteApprovalRequest
  • RemoteApprovalDecision

180.C.03.07 adds stream source, descriptor, state, quality, health, and WebRTC signaling metadata schemas:

  • RemoteStreamDescriptor
  • RemoteStreamSource
  • RemoteStreamState
  • RemoteWebRtcSignalingMetadata

180.C.03.08 adds canonical command namespace constants:

  • REMOTE_COMMAND_NAMESPACE
  • REMOTE_COMMAND_NAMESPACE_VALUES
  • REMOTE_COMMAND_NAMESPACE_PATTERN
  • REMOTE_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:

  • RemoteProtocolCompatibilityPolicy
  • RemoteProtocolCompatibilityRule
  • RemoteProtocolDeprecationPolicy
  • RemoteProtocolPeerVersion
  • RemoteProtocolVersionNegotiation
  • version comparison and selection helpers for host/gateway handshake tests

180.C.03.12 adds structured remediation to every protocol command error:

  • RemoteCommandErrorRemediation
  • RemoteSuggestedNextCommandTemplate
  • createRemoteCommandError()
  • 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:

  • RemoteActor
  • RemoteActorKind
  • RemoteActorChain

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:

  • RemoteRollbackStrategy
  • RemoteCommandMetadata

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:

  • RemoteAgentReadinessCommandName
  • RemoteStateSnapshotCommandName
  • RemoteAgentReadinessCommandArguments
  • RemoteStateSnapshotCommandArguments
  • RemoteAgentReadiness
  • RemoteStateSnapshot
  • RemoteModalDialogState
  • RemoteShaderCompileState
  • RemoteProjectRootState
  • RemoteRunningJob
  • RemoteDynamicResourcePressure

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:

  • RemoteDryRunPlan
  • RemoteDryRunRequiredRiskClass
  • RemoteDryRunPredictedChange
  • RemoteDryRunCostEstimate
  • RemoteDryRunTimeEstimate
  • RemoteDryRunReversibilityAssessment

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:

  • RemoteBlenderSceneInfoCommandName
  • RemoteBlenderSceneInfoCommandArguments
  • RemoteBlenderSceneInfo
  • RemoteBlenderScene
  • RemoteBlenderCollection
  • RemoteBlenderObject
  • RemoteBlenderMaterial
  • RemoteBlenderCamera
  • RemoteBlenderLight

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:

  • RemoteBlenderCreatePrimitiveCommandName
  • RemoteBlenderCreatePrimitiveCommandArguments
  • RemoteBlenderCreatePrimitiveCommandMetadata
  • RemoteBlenderCreatePrimitiveCommandEnvelope
  • RemoteBlenderPrimitiveType
  • RemoteBlenderCreatePrimitiveTransform
  • RemoteBlenderCreatePrimitiveCollectionReference
  • RemoteBlenderCreatePrimitiveMaterialReference

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:

  • RemoteBlenderObjectDeleteCommandArguments
  • RemoteBlenderObjectRenameCommandArguments
  • RemoteBlenderObjectDuplicateCommandArguments
  • RemoteBlenderObjectParentCommandArguments
  • RemoteBlenderObjectSetTransformCommandArguments
  • RemoteBlenderObjectSetVisibilityCommandArguments
  • RemoteBlenderObjectMutationTransform
  • RemoteBlenderObjectVisibilityState
  • RemoteBlenderUndoCheckpoint
  • RemoteBlenderSceneMutationEvidenceReferences
  • RemoteBlenderObjectMutationResult

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:

  • RemoteBlenderCollectionCreateCommandArguments
  • RemoteBlenderCollectionMoveObjectCommandArguments
  • RemoteBlenderCollectionSetVisibilityCommandArguments
  • RemoteBlenderCollectionSetRenderabilityCommandArguments
  • RemoteBlenderCollectionHierarchyCommandArguments
  • RemoteBlenderCollectionVisibilityState
  • RemoteBlenderCollectionRenderabilityState
  • RemoteBlenderCollectionMutationResult
  • RemoteBlenderCollectionHierarchyResult

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:

  • RemoteBlenderMaterialCreatePrincipledCommandArguments
  • RemoteBlenderMaterialAssignCommandArguments
  • RemoteBlenderMaterialSetParameterCommandArguments
  • RemoteBlenderMaterialBindTextureCommandArguments
  • RemoteBlenderMaterialSemanticSearchCommandArguments
  • RemoteBlenderMaterialParameterName
  • RemoteBlenderMaterialParameterValue
  • RemoteBlenderMaterialTextureSlot
  • RemoteBlenderMaterialTextureColorSpace
  • RemoteBlenderMaterialMutationResult
  • RemoteBlenderMaterialSemanticSearchResult

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:

  • RemoteBlenderModifierAddCommandArguments
  • RemoteBlenderModifierConfigureCommandArguments
  • RemoteBlenderModifierReorderCommandArguments
  • RemoteBlenderModifierSetViewportEnabledCommandArguments
  • RemoteBlenderModifierSetRenderEnabledCommandArguments
  • RemoteBlenderModifierApplyCommandArguments
  • RemoteBlenderModifierPropertyValue
  • RemoteBlenderModifierStackEntry
  • RemoteBlenderModifierStackSnapshot
  • RemoteBlenderModifierMutationResult

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:

  • RemoteBlenderGeometryNodesListMacrosCommandArguments
  • RemoteBlenderGeometryNodesApplyMacroCommandArguments
  • RemoteBlenderGeometryNodesMacroId
  • RemoteBlenderGeometryNodesMacroDescriptor
  • RemoteBlenderGeometryNodesPlanSummary
  • RemoteBlenderGeometryNodesListMacrosResult
  • RemoteBlenderGeometryNodesMacroMutationResult

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:

  • RemoteBlenderMeshEditListMacrosCommandArguments
  • RemoteBlenderMeshEditApplyMacroCommandArguments
  • RemoteBlenderMeshEditMacroId
  • RemoteBlenderMeshSelectionDomain
  • RemoteBlenderMeshEditMacroDescriptor
  • RemoteBlenderMeshEditSelectionSnapshot
  • RemoteBlenderMeshEditListMacrosResult
  • RemoteBlenderMeshEditMacroMutationResult

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:

  • RemoteBlenderAssetImportCommandArguments
  • RemoteBlenderAssetImportCommandMetadata
  • RemoteBlenderAssetImportFormat
  • RemoteBlenderAssetImportSourceKind
  • RemoteBlenderAssetImportProvenanceReferences
  • RemoteBlenderAssetImportResult

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:

  • RemoteBlenderAssetExportCommandArguments
  • RemoteBlenderAssetExportCommandMetadata
  • RemoteBlenderAssetExportFormat
  • RemoteBlenderAssetExportImageSequence
  • RemoteBlenderAssetExportedFile
  • RemoteBlenderAssetExportTransferItem
  • RemoteBlenderAssetExportTransferReferences
  • RemoteBlenderAssetExportHashVerification
  • RemoteBlenderAssetExportResult

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:

  • RemoteBlenderSemanticSelectorKind
  • RemoteBlenderSemanticSelectorQueryCommandArguments
  • RemoteBlenderSemanticSelectorQueryCommandMetadata
  • RemoteBlenderSemanticSelectorQueryCommandTarget
  • RemoteBlenderSemanticSelectorQueryCommandEnvelope
  • RemoteBlenderSemanticSelectorObjectMatch
  • RemoteBlenderSemanticSelectorMaterialMatch
  • RemoteBlenderSemanticSelectorQueryResult

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:

  • RemoteUnrealProjectInfoCommandName
  • RemoteUnrealProjectInfoCommandArguments
  • RemoteUnrealReadonlyCommandMetadata
  • RemoteUnrealProjectInfoCommandEnvelope
  • RemoteUnrealProjectInfo
  • RemoteUnrealProjectPlugin
  • RemoteUnrealProjectModule
  • RemoteUnrealProjectBuildTarget

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:

  • RemoteUnrealWorldQueryCommandName
  • RemoteUnrealWorldQueryCommandArguments
  • RemoteUnrealWorldQueryCommandEnvelope
  • RemoteUnrealWorldQuery
  • RemoteUnrealWorldSummary
  • RemoteUnrealLevelSummary
  • RemoteUnrealActorSummary
  • RemoteUnrealWorldEditorState
  • RemoteUnrealWorldQueryBlocker

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:

  • RemoteUnrealActorSpawnCommandName
  • RemoteUnrealActorSpawnCommandArguments
  • RemoteUnrealActorSpawnCommandMetadata
  • RemoteUnrealActorSpawnCommandEnvelope
  • RemoteUnrealActorSpawnResult
  • RemoteUnrealActorReference
  • RemoteUnrealActorSpawnTransaction
  • RemoteUnrealActorSpawnEvidenceReferences

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:

  • RemoteBrowserLaunchManagedCommandArguments
  • RemoteBrowserNavigateCommandArguments
  • RemoteBrowserSnapshotCommandArguments
  • RemoteBrowserScreenshotCommandArguments
  • RemoteBrowserCloseCommandArguments
  • RemoteBrowserCompensatingAction
  • RemoteBrowserSafeMutationCommandMetadata
  • RemoteBrowserReadonlyCommandMetadata
  • RemoteBrowserManagedSession

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:

  • RemoteDesktopCompensatingAction
  • RemoteDesktopCompensatingActionKind
  • RemoteDesktopCompensatingActionVerification
  • RemoteDesktopMutatingCommandName

180.C.13.12 adds the keyboard-layout-aware desktop.type contract:

  • RemoteDesktopTypeCommandArguments
  • RemoteDesktopTypeCommandMetadata
  • RemoteDesktopTypeCommandEnvelope
  • RemoteDesktopKeyboardLayoutReport

180.C.13.13 adds stable display identity contracts:

  • RemoteDesktopDisplay
  • RemoteDesktopDisplaySelector
  • RemoteDesktopDisplayListCommandArguments
  • RemoteDesktopDisplayListCommandEnvelope
  • RemoteDesktopDisplayListResult

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:

  • RemoteDesktopClipboardCaptureCommandArguments
  • RemoteDesktopClipboardCaptureCommandEnvelope
  • RemoteDesktopClipboardCaptureRedactionPattern
  • RemoteDesktopClipboardCaptureResult

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_VALUES now 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 returns requires-approval for command or scope decisions that must be approved before dispatch.
  • RemoteCommandPolicyEvaluation is 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-protocol
  • pnpm nx build @bellona/remote-protocol
  • pnpm nx typecheck @bellona/remote-protocol
  • pnpm nx lint @bellona/remote-protocol
  • pnpm 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.