feat(sidecar): add provided_commands wire request for per-package command listing

Author: NathanFlurry

crates/sidecar-browser/src/wire_dispatch.rs

@@ -199,6 +199,17 @@ where
                     "link_package is not available in the converged browser runtime",
                 )
             }
+            RequestRoute::ProvidedCommands(payload) => {
+                // Provided command metadata is retained by the native sidecar's
+                // host-backed package projection, which the converged browser
+                // runtime does not provide.
+                let _ = payload;
+                rejected(
+                    &request,
+                    "unsupported",
+                    "provided_commands is not available in the converged browser runtime",
+                )
+            }
             RequestRoute::UnsupportedHostCallbackDirection => {
                 unsupported_host_callback_direction_dispatch(&request)
             }

crates/sidecar-core/src/frames.rs

@@ -1,15 +1,16 @@
 use secure_exec_sidecar_protocol::protocol::{
     AuthenticateRequest, AuthenticatedResponse, BoundUdpSnapshotResponse, EventFrame, EventPayload,
     LayerCreatedResponse, LayerSealedResponse, ListenerSnapshotResponse, OverlayCreatedResponse,
-    OwnershipScope, PackageLinkedResponse, ProcessExitedEvent, ProcessKilledResponse,
-    ProcessOutputEvent, ProcessSnapshotEntry, ProcessSnapshotResponse, ProcessStartedResponse,
-    ProjectedCommand, ProtocolSchema, RejectedResponse, RequestFrame, RequestId, ResponseFrame,
-    ResponsePayload, RootFilesystemBootstrappedResponse, RootFilesystemEntry,
-    RootFilesystemSnapshotResponse, SessionOpenedResponse, SignalHandlerRegistration,
-    SignalStateResponse, SnapshotExportedResponse, SnapshotImportedResponse, SocketStateEntry,
-    StdinClosedResponse, StdinWrittenResponse, StreamChannel, StructuredEvent,
-    VmConfiguredResponse, VmCreatedResponse, VmDisposedResponse, VmLifecycleEvent,
-    VmLifecycleState, ZombieTimerCountResponse, PROTOCOL_VERSION,
+    OwnershipScope, PackageCommands, PackageLinkedResponse, ProcessExitedEvent,
+    ProcessKilledResponse, ProcessOutputEvent, ProcessSnapshotEntry, ProcessSnapshotResponse,
+    ProcessStartedResponse, ProjectedCommand, ProtocolSchema, ProvidedCommandsResponse,
+    RejectedResponse, RequestFrame, RequestId, ResponseFrame, ResponsePayload,
+    RootFilesystemBootstrappedResponse, RootFilesystemEntry, RootFilesystemSnapshotResponse,
+    SessionOpenedResponse, SignalHandlerRegistration, SignalStateResponse,
+    SnapshotExportedResponse, SnapshotImportedResponse, SocketStateEntry, StdinClosedResponse,
+    StdinWrittenResponse, StreamChannel, StructuredEvent, VmConfiguredResponse, VmCreatedResponse,
+    VmDisposedResponse, VmLifecycleEvent, VmLifecycleState, ZombieTimerCountResponse,
+    PROTOCOL_VERSION,
 };
 use std::collections::HashMap;
 
@@ -172,9 +173,17 @@ pub fn package_linked_response(
 ) -> ResponseFrame {
     respond(
         request,
-        ResponsePayload::PackageLinked(PackageLinkedResponse {
-            projected_commands,
-        }),
+        ResponsePayload::PackageLinked(PackageLinkedResponse { projected_commands }),
+    )
+}
+
+pub fn provided_commands_response(
+    request: &RequestFrame,
+    packages: Vec<PackageCommands>,
+) -> ResponseFrame {
+    respond(
+        request,
+        ResponsePayload::ProvidedCommands(ProvidedCommandsResponse { packages }),
     )
 }
 

crates/sidecar-core/src/lib.rs

@@ -31,13 +31,13 @@ pub use frames::{
     authenticated_response, bound_udp_snapshot_response, event, layer_created_response,
     layer_sealed_response, listener_snapshot_response, overlay_created_response,
     package_linked_response, process_exited_event, process_killed_response, process_output_event,
-    process_snapshot_response, process_started_response, reject, respond, response_with_ownership,
-    root_filesystem_bootstrapped_response, root_filesystem_snapshot_response,
-    session_opened_response, signal_state_response, snapshot_exported_response,
-    snapshot_imported_response, stdin_closed_response, stdin_written_response,
-    unsupported_guest_kernel_call_detail, unsupported_guest_kernel_call_event,
-    validate_authenticate_versions, vm_configured_response, vm_created_response,
-    vm_disposed_response, vm_lifecycle_event, zombie_timer_count_response,
+    process_snapshot_response, process_started_response, provided_commands_response, reject,
+    respond, response_with_ownership, root_filesystem_bootstrapped_response,
+    root_filesystem_snapshot_response, session_opened_response, signal_state_response,
+    snapshot_exported_response, snapshot_imported_response, stdin_closed_response,
+    stdin_written_response, unsupported_guest_kernel_call_detail,
+    unsupported_guest_kernel_call_event, validate_authenticate_versions, vm_configured_response,
+    vm_created_response, vm_disposed_response, vm_lifecycle_event, zombie_timer_count_response,
     AuthenticateVersionError, DispatchResult, UNSUPPORTED_GUEST_KERNEL_CALL_EVENT,
 };
 pub use guest_fs::{

crates/sidecar-core/src/router.rs

@@ -6,8 +6,9 @@ use secure_exec_sidecar_protocol::protocol::{
     GetProcessSnapshotRequest, GetResourceSnapshotRequest, GetSignalStateRequest,
     GetZombieTimerCountRequest, GuestFilesystemCallRequest, GuestKernelCallRequest,
     ImportSnapshotRequest, KillProcessRequest, LinkPackageRequest, OpenSessionRequest,
-    OwnershipScope, RegisterHostCallbacksRequest, RequestFrame, RequestPayload, ResizePtyRequest,
-    SealLayerRequest, SnapshotRootFilesystemRequest, VmFetchRequest, WriteStdinRequest,
+    OwnershipScope, ProvidedCommandsRequest, RegisterHostCallbacksRequest, RequestFrame,
+    RequestPayload, ResizePtyRequest, SealLayerRequest, SnapshotRootFilesystemRequest,
+    VmFetchRequest, WriteStdinRequest,
 };
 use secure_exec_sidecar_protocol::wire as generated_wire;
 
@@ -54,6 +55,7 @@ pub enum RequestRoute {
     GetSignalState(GetSignalStateRequest),
     GetZombieTimerCount(GetZombieTimerCountRequest),
     LinkPackage(LinkPackageRequest),
+    ProvidedCommands(ProvidedCommandsRequest),
     Ext(ExtEnvelope),
     UnsupportedHostCallbackDirection,
 }
@@ -100,6 +102,7 @@ pub fn route_request_payload(request: &RequestFrame) -> RequestRoute {
         RequestPayload::GetSignalState(payload) => RequestRoute::GetSignalState(payload),
         RequestPayload::GetZombieTimerCount(payload) => RequestRoute::GetZombieTimerCount(payload),
         RequestPayload::LinkPackage(payload) => RequestRoute::LinkPackage(payload),
+        RequestPayload::ProvidedCommands(payload) => RequestRoute::ProvidedCommands(payload),
         RequestPayload::HostFilesystemCall(_)
         | RequestPayload::PersistenceLoad(_)
         | RequestPayload::PersistenceFlush(_) => RequestRoute::UnsupportedHostCallbackDirection,
@@ -162,6 +165,7 @@ pub fn request_dispatch_mode(request: &RequestFrame) -> RequestDispatchMode {
         | RequestPayload::GetSignalState(_)
         | RequestPayload::GetZombieTimerCount(_)
         | RequestPayload::LinkPackage(_)
+        | RequestPayload::ProvidedCommands(_)
         | RequestPayload::HostFilesystemCall(_)
         | RequestPayload::PersistenceLoad(_)
         | RequestPayload::PersistenceFlush(_) => RequestDispatchMode::Immediate,

crates/sidecar-protocol/protocol/secure_exec_sidecar_v1.bare

@@ -221,6 +221,17 @@ type LinkPackageRequest struct {
   package: PackageDescriptor
 }
 
+type PackageCommands struct {
+  packageName: str
+  commands: list<str>
+}
+
+type ProvidedCommandsRequest void
+
+type ProvidedCommandsResponse struct {
+  packages: list<PackageCommands>
+}
+
 type ProjectedCommand struct {
   name: str
   guestPath: str
@@ -456,7 +467,8 @@ type RequestPayload union {
   GuestKernelCallRequest |
   ResizePtyRequest |
   GetResourceSnapshotRequest |
-  LinkPackageRequest
+  LinkPackageRequest |
+  ProvidedCommandsRequest
 }
 
 type RequestFrame struct {
@@ -742,7 +754,8 @@ type ResponsePayload union {
   GuestKernelResultResponse |
   PtyResizedResponse |
   ResourceSnapshotResponse |
-  PackageLinkedResponse
+  PackageLinkedResponse |
+  ProvidedCommandsResponse
 }
 
 type ResponseFrame struct {

crates/sidecar-protocol/src/protocol.rs

@@ -497,6 +497,9 @@ fn to_generated_request_payload(
         RequestPayload::LinkPackage(inner) => {
             generated_protocol::RequestPayload::LinkPackageRequest(inner.clone())
         }
+        RequestPayload::ProvidedCommands(_) => {
+            generated_protocol::RequestPayload::ProvidedCommandsRequest
+        }
     })
 }
 
@@ -602,6 +605,9 @@ fn from_generated_request_payload(
         generated_protocol::RequestPayload::LinkPackageRequest(inner) => {
             RequestPayload::LinkPackage(inner)
         }
+        generated_protocol::RequestPayload::ProvidedCommandsRequest => {
+            RequestPayload::ProvidedCommands(ProvidedCommandsRequest {})
+        }
     })
 }
 
@@ -753,6 +759,9 @@ fn to_generated_response_payload(
         ResponsePayload::PackageLinked(inner) => {
             generated_protocol::ResponsePayload::PackageLinkedResponse(inner.clone())
         }
+        ResponsePayload::ProvidedCommands(inner) => {
+            generated_protocol::ResponsePayload::ProvidedCommandsResponse(inner.clone())
+        }
     })
 }
 
@@ -891,6 +900,9 @@ fn from_generated_response_payload(
         generated_protocol::ResponsePayload::PackageLinkedResponse(inner) => {
             ResponsePayload::PackageLinked(inner)
         }
+        generated_protocol::ResponsePayload::ProvidedCommandsResponse(inner) => {
+            ResponsePayload::ProvidedCommands(inner)
+        }
     })
 }
 
@@ -1257,6 +1269,7 @@ pub enum RequestPayload {
     ResizePty(ResizePtyRequest),
     GetResourceSnapshot(GetResourceSnapshotRequest),
     LinkPackage(LinkPackageRequest),
+    ProvidedCommands(ProvidedCommandsRequest),
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -1295,6 +1308,7 @@ pub enum ResponsePayload {
     PtyResized(PtyResizedResponse),
     ResourceSnapshot(ResourceSnapshotResponse),
     PackageLinked(PackageLinkedResponse),
+    ProvidedCommands(ProvidedCommandsResponse),
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -1399,12 +1413,17 @@ pub type GuestFilesystemCallRequest = crate::wire::GuestFilesystemCallRequest;
 pub type GuestKernelCallRequest = crate::wire::GuestKernelCallRequest;
 pub type ResizePtyRequest = crate::wire::ResizePtyRequest;
 pub type PackageDescriptor = crate::wire::PackageDescriptor;
+pub type PackageCommands = crate::wire::PackageCommands;
 pub type ProjectedCommand = crate::wire::ProjectedCommand;
 pub type LinkPackageRequest = crate::wire::LinkPackageRequest;
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub struct ProvidedCommandsRequest {}
+
 pub type GuestKernelResultResponse = crate::wire::GuestKernelResultResponse;
 pub type PtyResizedResponse = crate::wire::PtyResizedResponse;
 pub type PackageLinkedResponse = crate::wire::PackageLinkedResponse;
+pub type ProvidedCommandsResponse = crate::wire::ProvidedCommandsResponse;
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
 pub struct SnapshotRootFilesystemRequest {}
@@ -1598,6 +1617,7 @@ impl_bare_newtype_union_enum!(
         ResizePty(ResizePtyRequest) = 29,
         GetResourceSnapshot(GetResourceSnapshotRequest) = 30,
         LinkPackage(LinkPackageRequest) = 31,
+        ProvidedCommands(ProvidedCommandsRequest) = 32,
     }
 );
 
@@ -1640,6 +1660,7 @@ impl_bare_newtype_union_enum!(
         PtyResized(PtyResizedResponse) = 31,
         ResourceSnapshot(ResourceSnapshotResponse) = 32,
         PackageLinked(PackageLinkedResponse) = 33,
+        ProvidedCommands(ProvidedCommandsResponse) = 34,
     }
 );
 
@@ -2220,6 +2241,7 @@ enum ExpectedResponseKind {
     GuestKernelResult,
     PtyResized,
     PackageLinked,
+    ProvidedCommands,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -2265,6 +2287,7 @@ impl ExpectedResponseKind {
             Self::GuestKernelResult => "guest_kernel_result",
             Self::PtyResized => "pty_resized",
             Self::PackageLinked => "package_linked",
+            Self::ProvidedCommands => "provided_commands_response",
         }
     }
 
@@ -2322,6 +2345,7 @@ impl RequestPayload {
             | Self::GuestKernelCall(_)
             | Self::ResizePty(_)
             | Self::LinkPackage(_)
+            | Self::ProvidedCommands(_)
             | Self::HostFilesystemCall(_) => OwnershipRequirement::Vm,
             Self::Ext(_) => OwnershipRequirement::Any,
         }
@@ -2361,6 +2385,7 @@ impl RequestPayload {
             Self::GuestKernelCall(_) => ExpectedResponseKind::GuestKernelResult,
             Self::ResizePty(_) => ExpectedResponseKind::PtyResized,
             Self::LinkPackage(_) => ExpectedResponseKind::PackageLinked,
+            Self::ProvidedCommands(_) => ExpectedResponseKind::ProvidedCommands,
         }
     }
 }
@@ -2413,7 +2438,8 @@ impl ResponsePayload {
             | Self::PermissionDecision(_)
             | Self::GuestKernelResult(_)
             | Self::PtyResized(_)
-            | Self::PackageLinked(_) => OwnershipRequirement::Vm,
+            | Self::PackageLinked(_)
+            | Self::ProvidedCommands(_) => OwnershipRequirement::Vm,
             Self::ExtResult(_) => OwnershipRequirement::Any,
         }
     }
@@ -2454,6 +2480,7 @@ impl ResponsePayload {
             Self::GuestKernelResult(_) => "guest_kernel_result",
             Self::PtyResized(_) => "pty_resized",
             Self::PackageLinked(_) => "package_linked",
+            Self::ProvidedCommands(_) => "provided_commands_response",
         }
     }
 }

crates/sidecar/src/service.rs

@@ -1214,6 +1214,9 @@ where
                 self.get_zombie_timer_count(&request, payload).await
             }
             RequestRoute::LinkPackage(payload) => self.link_package(&request, payload).await,
+            RequestRoute::ProvidedCommands(payload) => {
+                self.provided_commands(&request, payload).await
+            }
             RequestRoute::UnsupportedHostCallbackDirection => {
                 Ok(unsupported_host_callback_direction_dispatch(&request))
             }

crates/sidecar/src/state.rs

@@ -290,6 +290,7 @@ pub(crate) struct VmConfiguration {
     pub(crate) instructions: Vec<String>,
     pub(crate) projected_modules: Vec<ProjectedModuleDescriptor>,
     pub(crate) command_permissions: BTreeMap<String, WasmPermissionTier>,
+    pub(crate) provided_commands: BTreeMap<String, Vec<String>>,
     /// Guest JavaScript host-environment config (platform / module resolution /
     /// builtin allow-list). Set at `create_vm` from `CreateVmConfig.jsRuntime`
     /// and preserved across `configure_vm`. `None` => full Node.js emulation.
@@ -310,6 +311,7 @@ impl Default for VmConfiguration {
             instructions: Vec::new(),
             projected_modules: Vec::new(),
             command_permissions: BTreeMap::new(),
+            provided_commands: BTreeMap::new(),
             js_runtime: None,
             snapshot_userland_code: None,
             loopback_exempt_ports: Vec::new(),
@@ -339,6 +341,7 @@ pub(crate) struct VmState {
     pub(crate) configuration: VmConfiguration,
     pub(crate) layers: VmLayerStore,
     pub(crate) command_guest_paths: BTreeMap<String, String>,
+    pub(crate) provided_commands: BTreeMap<String, Vec<String>>,
     pub(crate) command_permissions: BTreeMap<String, WasmPermissionTier>,
     pub(crate) toolkits: BTreeMap<String, RegisterHostCallbacksRequest>,
     pub(crate) active_processes: BTreeMap<String, ActiveProcess>,