# @bellona/remote-protocol 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:` 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.