[LXC] Implement StatefulSandboxBackend for LXC (state-aware lifecycle) (AB#62953349)

Provision/start/exec/stop/deprovision for the LXC backend, modeled on IsolationSessionRunner; reuses lxc CLI wrappers and one-shot lxc-attach PTY streaming. Registers the lxc wire key in Rust dispatch/parser and SDK state-aware routing.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3b78bec0-e139-4cfd-9c10-092ef986d4f4

Author: dhoehna

sdk/src/state-aware-helper.ts

@@ -13,18 +13,20 @@ export const STATE_AWARE_VERSION = '0.6.0-alpha';
 // Wire-format cross-cutting fields that live at the envelope's top level.
 // Anything else on a per-(backend, phase) Config is backend-specific and is
 // nested under `experimental.<backend>.<phase>`.
-export const CROSS_CUTTING_FIELDS = ['filesystem', 'network', 'ui', 'process'] as const;
+export const CROSS_CUTTING_FIELDS = ['containerId', 'filesystem', 'network', 'ui', 'process'] as const;
 
 // Per-backend wire-format prefix. Each value mirrors the corresponding
 // Rust `<Backend>Runner::ID_PREFIX` const and is the leading segment of a
 // `sandboxId` produced by that backend. Each future state-aware backend
 // declares its own `<BACKEND>_ID_PREFIX` const here.
 export const ISOLATION_SESSION_ID_PREFIX = 'iso';
+export const LXC_ID_PREFIX = 'lxc';
 
 // Mapping from a sandboxId's leading prefix segment to the wire-format
 // backend key. Extended as more state-aware backends opt in.
 export const PREFIX_TO_BACKEND: Record<string, StateAwareContainmentBackend> = {
   [ISOLATION_SESSION_ID_PREFIX]: 'isolation_session',
+  [LXC_ID_PREFIX]: 'lxc',
 };
 
 /**

sdk/src/state-aware-types.ts

@@ -4,6 +4,7 @@
 import {
   ContainmentBackend,
   FilesystemConfig,
+  NetworkConfig,
   ProcessConfig,
 } from './types.js';
 
@@ -16,7 +17,7 @@ export type Phase = 'provision' | 'start' | 'exec' | 'stop' | 'deprovision';
  * Subset of `ContainmentBackend` whose backends participate in the state-aware
  * lifecycle. Extended as more backends opt in.
  */
-export type StateAwareContainmentBackend = Extract<ContainmentBackend, 'isolation_session'>;
+export type StateAwareContainmentBackend = Extract<ContainmentBackend, 'isolation_session' | 'lxc'>;
 
 /**
  * Branded sandbox identifier returned by `provisionSandbox` and routed back
@@ -99,6 +100,42 @@ export interface IsolationSessionDeprovisionConfig {
   version?: string;
 }
 
+export interface LxcProvisionConfig {
+  /** Schema version (semver). */
+  version?: string;
+  /** Optional externally assigned LXC container name. */
+  containerId?: string;
+  /** Linux distribution for the container rootfs, e.g. "alpine" or "ubuntu". */
+  distribution: string;
+  /** Distribution release version, e.g. "3.20" or "24.04". */
+  release: string;
+}
+
+export interface LxcStartConfig {
+  /** Schema version (semver). */
+  version?: string;
+  /** Filesystem mounts to apply before starting the container. */
+  filesystem?: FilesystemConfig;
+  /** iptables policy to apply after the container starts. */
+  network?: NetworkConfig;
+}
+
+export interface LxcExecConfig {
+  /** Schema version (semver). */
+  version?: string;
+  process: ProcessConfig;
+}
+
+export interface LxcStopConfig {
+  /** Schema version (semver). */
+  version?: string;
+}
+
+export interface LxcDeprovisionConfig {
+  /** Schema version (semver). */
+  version?: string;
+}
+
 /**
  * IsolationSession's provision-phase metadata: the per-instance agent user
  * account name minted for this sandbox.
@@ -107,6 +144,11 @@ export interface IsolationSessionProvisionMetadata {
   agentUserName: string;
 }
 
+export interface LxcProvisionMetadata {
+  containerName: string;
+  created: boolean;
+}
+
 /**
  * Per-backend per-phase typed Config bundle. Selects the correct Config
  * bundle for the backend type parameter.
@@ -120,6 +162,14 @@ export type ConfigsForBackend<C extends StateAwareContainmentBackend> =
         stop: IsolationSessionStopConfig;
         deprovision: IsolationSessionDeprovisionConfig;
       }
+    : C extends 'lxc'
+      ? {
+          provision: LxcProvisionConfig;
+          start: LxcStartConfig;
+          exec: LxcExecConfig;
+          stop: LxcStopConfig;
+          deprovision: LxcDeprovisionConfig;
+        }
     : never;
 
 export type ProvisionConfigFor<C extends StateAwareContainmentBackend> =
@@ -142,7 +192,10 @@ export interface StateAwareMetadata {
     provision?: IsolationSessionProvisionMetadata;
     // IsolationSession returns no metadata for start, stop, or deprovision.
   };
-  // Future state-aware-capable backends add typed entries here.
+  lxc?: {
+    provision?: LxcProvisionMetadata;
+    // LXC returns no metadata for start, stop, or deprovision.
+  };
 }
 
 type MetadataForPhase<C extends StateAwareContainmentBackend, Phase extends string> =

src/Cargo.lock

@@ -6,3 +6,4 @@ pub mod lxc_bindings;
 pub mod lxc_runner;
 pub mod network_iptables;
 pub mod signal_cleanup;
+pub mod state_aware;