feat(packages): sidecar package projection + agentos-toolchain + { packageDir } registry (#150)

Ports the package-projection feature onto the converged-runtime sidecar
(crate split sidecar/sidecar-core/sidecar-protocol): PackageDescriptor /
LinkPackageRequest / PackageLinkedResponse wire types, ConfigureVm packages
projection into /opt/agentos, runtime LinkPackage, and package_projection.rs.
Also: agentos-toolchain, @agentos-software/manifest, { packageDir } registry
migration, single base-filesystem.

Author: NathanFlurry

.gitignore

@@ -43,12 +43,18 @@ registry/native/c/vendor/
 registry/native/c/libs/
 registry/native/c/.cache/
 registry/native/c/sysroot/
+registry/software/*/bin/
 registry/software/*/wasm/
 registry/software/*/agent-os-package.meta.json
 registry/.last-publish-hash
 registry/software/*/.last-publish-hash
 registry/.build-markers/
 
+# Experiments C build artifacts
+experiments/wasm-gui/third_party/**/*.o
+experiments/wasm-gui/third_party/**/*.a
+experiments/wasm-gui/third_party/**/.libs/
+
 # Ralph agent artifacts
 scripts/ralph/archive/
 scripts/ralph/codex-streams/
@@ -70,6 +76,8 @@ crates/execution/.agent-os-pyodide-cache/
 crates/execution/async-out.txt
 crates/sidecar/.tmp-sidecar-tests/
 packages/browser/.cache/
+website/.astro/
+website/public/docs/
 
 # Vendored V8 bridge bundles staged at release time for crates.io publishing
 crates/execution/assets/generated/

CLAUDE.md

@@ -60,7 +60,7 @@ Every bound that protects a shared resource — memory/heap, CPU/wall-clock, fd/
 ## Build And Assets
 
 - The VM base filesystem artifact is derived from Alpine Linux, but runtime source should stay generic.
-- Rebuild the base filesystem with `pnpm --dir packages/build-tools snapshot:alpine-defaults`, then `pnpm --dir packages/build-tools build:base-filesystem`.
+- Rebuild the base filesystem (requires Docker) with `pnpm --dir packages/build-tools build:base-filesystem`. The one script snapshots Alpine, applies the secure-exec transforms, and writes the single canonical `packages/core/fixtures/base-filesystem.json`, mirroring the same bytes into the crate-vendored `crates/sidecar/assets/` and `crates/vfs/assets/` copies (those exist only as the `cargo publish` fallback; never hand-edit them).
 - The V8 bridge bundle is generated from `packages/build-tools/scripts/build-v8-bridge.mjs`; keep its generated assets aligned with bridge-contract changes.
 - `registry/native` owns the Rust-to-WASM command build; package-local `registry/software/*/wasm/` output is release material.
 

crates/execution/src/wasm.rs

@@ -55,7 +55,7 @@ const DEFAULT_WASM_GUEST_HOME: &str = "/root";
 const DEFAULT_WASM_GUEST_USER: &str = "root";
 const DEFAULT_WASM_GUEST_SHELL: &str = "/bin/sh";
 const DEFAULT_WASM_GUEST_PATH: &str =
-    "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+    "/usr/local/sbin:/usr/local/bin:/opt/agentos/bin:/usr/sbin:/usr/bin:/sbin:/bin";
 // Warmup is a best-effort compile-cache optimization; fall back to a cold start
 // instead of burning minutes on a stalled prewarm session.
 const DEFAULT_WASM_PREWARM_TIMEOUT_MS: u64 = 30_000;

crates/sidecar-core/src/frames.rs

@@ -4,7 +4,8 @@ use secure_exec_sidecar_protocol::protocol::{
     OwnershipScope, ProcessExitedEvent, ProcessKilledResponse, ProcessOutputEvent,
     ProcessSnapshotEntry, ProcessSnapshotResponse, ProcessStartedResponse, ProtocolSchema,
     RejectedResponse, RequestFrame, RequestId, ResponseFrame, ResponsePayload,
-    RootFilesystemBootstrappedResponse, RootFilesystemEntry, RootFilesystemSnapshotResponse,
+    PackageLinkedResponse, RootFilesystemBootstrappedResponse, RootFilesystemEntry,
+    RootFilesystemSnapshotResponse,
     SessionOpenedResponse, SignalHandlerRegistration, SignalStateResponse,
     SnapshotExportedResponse, SnapshotImportedResponse, SocketStateEntry, StdinClosedResponse,
     StdinWrittenResponse, StreamChannel, StructuredEvent, VmConfiguredResponse, VmCreatedResponse,
@@ -164,6 +165,13 @@ pub fn vm_configured_response(
     )
 }
 
+pub fn package_linked_response(request: &RequestFrame, commands: Vec<String>) -> ResponseFrame {
+    respond(
+        request,
+        ResponsePayload::PackageLinked(PackageLinkedResponse { commands }),
+    )
+}
+
 pub fn layer_created_response(request: &RequestFrame, layer_id: String) -> ResponseFrame {
     respond(
         request,

crates/sidecar-core/src/lib.rs

@@ -30,6 +30,7 @@ pub use diagnostics::{
 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,

crates/sidecar-core/src/router.rs

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

crates/sidecar-protocol/protocol/secure_exec_sidecar_v1.bare

@@ -208,6 +208,23 @@ type WasmPermissionTier enum {
   ISOLATED
 }
 
+# agentOS package descriptor. The sidecar reads `<dir>/agentos-package.json`,
+# projects the self-contained `dir` read-only under
+# `<packagesMountAt>/<manifest.name>/<package.json version>`, and links its `bin/`
+# commands onto $PATH. `dir` is a trusted host path (the client configures its own
+# VM); the sidecar is the host-side TCB that builds the staging tree.
+type PackageDescriptor struct {
+  dir: str
+}
+
+type LinkPackageRequest struct {
+  package: PackageDescriptor
+}
+
+type PackageLinkedResponse struct {
+  commands: list<str>
+}
+
 type ConfigureVmRequest struct {
   mounts: list<MountDescriptor>
   software: list<SoftwareDescriptor>
@@ -217,6 +234,8 @@ type ConfigureVmRequest struct {
   projectedModules: list<ProjectedModuleDescriptor>
   commandPermissions: map<str><WasmPermissionTier>
   loopbackExemptPorts: list<u16>
+  packages: list<PackageDescriptor>
+  packagesMountAt: str
 }
 
 type RegisteredHostCallbackExample struct {
@@ -424,7 +443,8 @@ type RequestPayload union {
   ExtEnvelope |
   GuestKernelCallRequest |
   ResizePtyRequest |
-  GetResourceSnapshotRequest
+  GetResourceSnapshotRequest |
+  LinkPackageRequest
 }
 
 type RequestFrame struct {
@@ -706,7 +726,8 @@ type ResponsePayload union {
   ExtEnvelope |
   GuestKernelResultResponse |
   PtyResizedResponse |
-  ResourceSnapshotResponse
+  ResourceSnapshotResponse |
+  PackageLinkedResponse
 }
 
 type ResponseFrame struct {

crates/sidecar-protocol/src/protocol.rs

@@ -482,6 +482,9 @@ fn to_generated_request_payload(
         RequestPayload::ResizePty(inner) => {
             generated_protocol::RequestPayload::ResizePtyRequest(inner.clone())
         }
+        RequestPayload::LinkPackage(inner) => {
+            generated_protocol::RequestPayload::LinkPackageRequest(inner.clone())
+        }
     })
 }
 
@@ -584,6 +587,9 @@ fn from_generated_request_payload(
         generated_protocol::RequestPayload::ResizePtyRequest(inner) => {
             RequestPayload::ResizePty(inner)
         }
+        generated_protocol::RequestPayload::LinkPackageRequest(inner) => {
+            RequestPayload::LinkPackage(inner)
+        }
     })
 }
 
@@ -732,6 +738,9 @@ fn to_generated_response_payload(
         ResponsePayload::PtyResized(inner) => {
             generated_protocol::ResponsePayload::PtyResizedResponse(inner.clone())
         }
+        ResponsePayload::PackageLinked(inner) => {
+            generated_protocol::ResponsePayload::PackageLinkedResponse(inner.clone())
+        }
     })
 }
 
@@ -867,6 +876,9 @@ fn from_generated_response_payload(
         generated_protocol::ResponsePayload::PtyResizedResponse(inner) => {
             ResponsePayload::PtyResized(inner)
         }
+        generated_protocol::ResponsePayload::PackageLinkedResponse(inner) => {
+            ResponsePayload::PackageLinked(inner)
+        }
     })
 }
 
@@ -1232,6 +1244,7 @@ pub enum RequestPayload {
     GuestKernelCall(GuestKernelCallRequest),
     ResizePty(ResizePtyRequest),
     GetResourceSnapshot(GetResourceSnapshotRequest),
+    LinkPackage(LinkPackageRequest),
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -1269,6 +1282,7 @@ pub enum ResponsePayload {
     GuestKernelResult(GuestKernelResultResponse),
     PtyResized(PtyResizedResponse),
     ResourceSnapshot(ResourceSnapshotResponse),
+    PackageLinked(PackageLinkedResponse),
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -1372,9 +1386,12 @@ 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 LinkPackageRequest = crate::wire::LinkPackageRequest;
 
 pub type GuestKernelResultResponse = crate::wire::GuestKernelResultResponse;
 pub type PtyResizedResponse = crate::wire::PtyResizedResponse;
+pub type PackageLinkedResponse = crate::wire::PackageLinkedResponse;
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
 pub struct SnapshotRootFilesystemRequest {}
@@ -1567,6 +1584,7 @@ impl_bare_newtype_union_enum!(
         GuestKernelCall(GuestKernelCallRequest) = 28,
         ResizePty(ResizePtyRequest) = 29,
         GetResourceSnapshot(GetResourceSnapshotRequest) = 30,
+        LinkPackage(LinkPackageRequest) = 31,
     }
 );
 
@@ -1608,6 +1626,7 @@ impl_bare_newtype_union_enum!(
         GuestKernelResult(GuestKernelResultResponse) = 30,
         PtyResized(PtyResizedResponse) = 31,
         ResourceSnapshot(ResourceSnapshotResponse) = 32,
+        PackageLinked(PackageLinkedResponse) = 33,
     }
 );
 
@@ -2187,6 +2206,7 @@ enum ExpectedResponseKind {
     ExtResult,
     GuestKernelResult,
     PtyResized,
+    PackageLinked,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -2231,6 +2251,7 @@ impl ExpectedResponseKind {
             Self::ExtResult => "ext_result",
             Self::GuestKernelResult => "guest_kernel_result",
             Self::PtyResized => "pty_resized",
+            Self::PackageLinked => "package_linked",
         }
     }
 
@@ -2287,6 +2308,7 @@ impl RequestPayload {
             | Self::GetZombieTimerCount(_)
             | Self::GuestKernelCall(_)
             | Self::ResizePty(_)
+            | Self::LinkPackage(_)
             | Self::HostFilesystemCall(_) => OwnershipRequirement::Vm,
             Self::Ext(_) => OwnershipRequirement::Any,
         }
@@ -2325,6 +2347,7 @@ impl RequestPayload {
             Self::Ext(_) => ExpectedResponseKind::ExtResult,
             Self::GuestKernelCall(_) => ExpectedResponseKind::GuestKernelResult,
             Self::ResizePty(_) => ExpectedResponseKind::PtyResized,
+            Self::LinkPackage(_) => ExpectedResponseKind::PackageLinked,
         }
     }
 }
@@ -2376,7 +2399,8 @@ impl ResponsePayload {
             | Self::FilesystemResult(_)
             | Self::PermissionDecision(_)
             | Self::GuestKernelResult(_)
-            | Self::PtyResized(_) => OwnershipRequirement::Vm,
+            | Self::PtyResized(_)
+            | Self::PackageLinked(_) => OwnershipRequirement::Vm,
             Self::ExtResult(_) => OwnershipRequirement::Any,
         }
     }
@@ -2416,6 +2440,7 @@ impl ResponsePayload {
             Self::ExtResult(_) => "ext_result",
             Self::GuestKernelResult(_) => "guest_kernel_result",
             Self::PtyResized(_) => "pty_resized",
+            Self::PackageLinked(_) => "package_linked",
         }
     }
 }

crates/sidecar/src/lib.rs

@@ -15,6 +15,7 @@ pub mod limits;
 #[cfg(target_os = "macos")]
 pub(crate) mod macos_fs;
 pub(crate) mod metadata;
+pub mod package_projection;
 pub(crate) mod plugins;
 pub mod service;
 pub(crate) mod state;