microsandbox-rb 0.9.1 → 0.10.0

data/ext/microsandbox/src/image.rs

@@ -82,12 +82,12 @@ fn report_to_hash(report: ImagePruneReport) -> RHash {
 }
 
 fn get(reference: String) -> Result<RHash, Error> {
-    let handle = with_local_backend(async |local| Image::get(local, &reference).await)?;
+    let handle = with_local_backend(async |local| Image::get_local(local, &reference).await)?;
     Ok(handle_to_hash(&handle))
 }
 
 fn list() -> Result<RArray, Error> {
-    let handles = with_local_backend(async |local| Image::list(local).await)?;
+    let handles = with_local_backend(async |local| Image::list_local(local).await)?;
     let arr = ruby().ary_new();
     for h in handles.iter() {
         arr.push(handle_to_hash(h))?;
@@ -96,16 +96,16 @@ fn list() -> Result<RArray, Error> {
 }
 
 fn inspect(reference: String) -> Result<RHash, Error> {
-    let detail = with_local_backend(async |local| Image::inspect(local, &reference).await)?;
+    let detail = with_local_backend(async |local| Image::inspect_local(local, &reference).await)?;
     Ok(detail_to_hash(detail))
 }
 
 fn remove(reference: String, force: bool) -> Result<(), Error> {
-    with_local_backend(async |local| Image::remove(local, &reference, force).await)
+    with_local_backend(async |local| Image::remove_local(local, &reference, force).await)
 }
 
 fn prune() -> Result<RHash, Error> {
-    let report = with_local_backend(async |local| Image::prune(local).await)?;
+    let report = with_local_backend(async |local| Image::prune_local(local).await)?;
     Ok(report_to_hash(report))
 }
 

data/ext/microsandbox/src/lib.rs

@@ -34,7 +34,7 @@ fn version() -> String {
 /// helpers (Python/Node/Go).
 fn all_sandbox_metrics() -> Result<RHash, Error> {
     let map = backend::with_local_backend(async |local| {
-        microsandbox::sandbox::all_sandbox_metrics(local).await
+        microsandbox::sandbox::all_sandbox_metrics_local(local).await
     })?;
     let hash = runtime::ruby().hash_new();
     for (name, metrics) in &map {
@@ -113,7 +113,7 @@ fn resolved_msb_path() -> Result<String, Error> {
             available_when: "with the local backend".into(),
         })
     })?;
-    let path = microsandbox::config::resolve_msb_path(local.config()).map_err(error::to_ruby)?;
+    let path = local.config().resolve_msb_path().map_err(error::to_ruby)?;
     Ok(path.to_string_lossy().into_owned())
 }
 

data/ext/microsandbox/src/sandbox.rs

@@ -18,10 +18,11 @@ use microsandbox::logs::{
     LogCursor, LogEntry, LogOptions, LogSource, LogStreamOptions, LogStreamStart,
 };
 use microsandbox::sandbox::{
-    AttachOptionsBuilder, DiskImageFormat, FsEntry, FsEntryKind, FsMetadata, HostPermissions,
-    Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource, SandboxBuilder,
-    SandboxFilter, SandboxHandle, SandboxMetrics, SandboxStatus, SandboxStopResult, SecretBuilder,
-    SecurityProfile, StatVirtualization,
+    AttachOptionsBuilder, DiskImageFormat, EnvVar, FsEntry, FsEntryKind, FsMetadata,
+    HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
+    SandboxBuilder, SandboxFilter, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
+    SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
+    SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
 };
 use microsandbox::LogLevel;
 use microsandbox::MicrosandboxResult;
@@ -92,9 +93,19 @@ impl Sandbox {
         if let Some(v) = conv::opt_u8(opts, "cpus")? {
             b = b.cpus(v);
         }
+        // v0.6.6 (#1099): boot-time maximum vCPU / memory ceilings that a later
+        // live `modify` can grow up to. `cpus`/`memory` above already raise these
+        // to their own value if lower, so a bare `cpus`/`memory` still works;
+        // setting these explicitly reserves headroom for a live resize.
+        if let Some(v) = conv::opt_u8(opts, "max_cpus")? {
+            b = b.max_cpus(v);
+        }
         if let Some(v) = conv::opt_u32(opts, "memory")? {
             b = b.memory(v);
         }
+        if let Some(v) = conv::opt_u32(opts, "max_memory")? {
+            b = b.max_memory(v);
+        }
         if let Some(v) = conv::opt_string(opts, "workdir")? {
             b = b.workdir(v);
         }
@@ -584,6 +595,34 @@ impl Sandbox {
         Ok(metrics_to_hash(&m))
     }
 
+    //----------------------------------------------------------------------
+    // Health & modification (v0.6.6 / #1099)
+    //----------------------------------------------------------------------
+
+    /// Health-check the guest agent without refreshing the idle timer. Returns
+    /// `{ name, latency_secs }` (round-trip latency as f64 seconds; the Ruby
+    /// layer exposes both seconds and milliseconds).
+    fn ping(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.ping()).map_err(error::to_ruby)?;
+        Ok(ping_result_to_hash(&result))
+    }
+
+    /// Explicitly refresh the idle-activity timer. Returns
+    /// `{ name, activity_seq }`.
+    fn touch(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.touch()).map_err(error::to_ruby)?;
+        Ok(touch_result_to_hash(&result))
+    }
+
+    /// Plan or apply a live sandbox modification. `opts` is the string-keyed
+    /// modify Hash normalized by the Ruby layer; returns the resulting
+    /// `SandboxModificationPlan` as a JSON string, which the Ruby layer parses
+    /// into a `ModificationPlan`. Mirrors the Node native binding (native returns
+    /// JSON, the wrapper shapes it).
+    fn modify(&self, opts: RHash) -> Result<String, Error> {
+        run_modify(self.inner.modify(), opts)
+    }
+
     /// Read captured logs as an Array of Hashes. `opts`: tail, since_ms,
     /// until_ms, sources (Array of "stdout"/"stderr"/"output"/"system"/"all").
     fn logs(&self, opts: RHash) -> Result<RArray, Error> {
@@ -1736,6 +1775,133 @@ fn stop_result_to_hash(result: &SandboxStopResult) -> RHash {
     hash
 }
 
+//--------------------------------------------------------------------------------------------------
+// Health & live modification (v0.6.6 / #1099)
+//--------------------------------------------------------------------------------------------------
+
+/// A `SandboxPingResult` as `{ name, latency_secs }`. Latency is a `Duration`;
+/// we hand it to Ruby as f64 seconds and let the Ruby layer derive milliseconds
+/// (the Python/Node SDKs expose only `latency_ms`).
+fn ping_result_to_hash(result: &microsandbox::sandbox::SandboxPingResult) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("name", result.name.clone());
+    let _ = hash.aset("latency_secs", result.latency.as_secs_f64());
+    hash
+}
+
+/// A `SandboxTouchResult` as `{ name, activity_seq }`.
+fn touch_result_to_hash(result: &microsandbox::sandbox::SandboxTouchResult) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("name", result.name.clone());
+    let _ = hash.aset("activity_seq", result.activity_seq);
+    hash
+}
+
+/// Drive a modify builder to a plan (dry-run or apply) and return it serialized
+/// as a JSON string. Shared by `Sandbox::modify` and `SbHandle::modify`. The
+/// canonical `SandboxModificationPlan` serde shape (snake_case keys, literal-space
+/// enum strings) is parsed verbatim by the Ruby layer — matching the Python SDK's
+/// raw-dict contract rather than re-casing it.
+fn run_modify(builder: SandboxModificationBuilder, opts: RHash) -> Result<String, Error> {
+    let patch = build_modify_patch(opts)?;
+    let policy = conv::opt_string(opts, "policy")?.unwrap_or_else(|| "no_restart".to_string());
+    let dry_run = conv::opt_bool(opts, "dry_run")?;
+    let builder = apply_modify_policy(builder.with_patch(patch), &policy)?;
+    let plan = block_on(async move {
+        if dry_run {
+            builder.dry_run().await
+        } else {
+            builder.apply().await
+        }
+    })
+    .map_err(error::to_ruby)?;
+    serde_json::to_string(&plan)
+        .map_err(|e| error::base_error(format!("failed to serialize modification plan: {e}")))
+}
+
+/// Build the canonical `SandboxModificationPatch` from the modify Hash. Env and
+/// label pairs are sorted so repeated calls with the same arguments produce the
+/// same patch (and plan) ordering, mirroring the Python binding. `oci_upper_size`
+/// is deliberately not surfaced (CLI-only upstream; the Python/Node SDKs omit it
+/// too), so it stays unset via `..Default::default()`.
+fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
+    let mut env_pairs = conv::opt_string_map(opts, "env")?;
+    env_pairs.sort();
+    let mut label_pairs = conv::opt_string_map(opts, "labels")?;
+    label_pairs.sort();
+
+    Ok(SandboxModificationPatch {
+        cpus: conv::opt_u8(opts, "cpus")?,
+        max_cpus: conv::opt_u8(opts, "max_cpus")?,
+        memory_mib: conv::opt_u32(opts, "memory")?,
+        max_memory_mib: conv::opt_u32(opts, "max_memory")?,
+        env: env_pairs
+            .into_iter()
+            .map(|(k, v)| EnvVar::new(k, v))
+            .collect(),
+        env_remove: conv::opt_string_vec(opts, "remove_env")?,
+        labels: label_pairs,
+        labels_remove: conv::opt_string_vec(opts, "remove_labels")?,
+        workdir: conv::opt_string(opts, "workdir")?,
+        secrets: parse_modify_secrets(opts)?,
+        secrets_remove: conv::opt_string_vec(opts, "remove_secrets")?,
+        ..Default::default()
+    })
+}
+
+/// Parse the `secrets` modify option (an Array of string-keyed Hashes normalized
+/// by the Ruby layer) into canonical `SecretModificationPatch`es. Each Hash
+/// carries `name` plus at most one of `env`/`store` (source) or `value` (raw
+/// material) — the Ruby layer enforces that mutual exclusion — plus optional
+/// `placeholder` and `allowed_hosts`. The raw `value` moves straight into the
+/// `Zeroizing` field; it is never echoed in an error.
+fn parse_modify_secrets(opts: RHash) -> Result<Vec<SecretModificationPatch>, Error> {
+    let mut out = Vec::new();
+    for h in conv::opt_hash_vec(opts, "secrets")? {
+        let name = conv::opt_string(h, "name")?
+            .ok_or_else(|| error::base_error("secret modification spec requires :name"))?;
+        let env = conv::opt_string(h, "env")?;
+        let store = conv::opt_string(h, "store")?;
+        let value = conv::opt_string(h, "value")?;
+        let source = match (env, store) {
+            (Some(var), None) => Some(SecretSource::Env { var }),
+            (None, Some(reference)) => Some(SecretSource::Store { reference }),
+            (None, None) => None,
+            // The Ruby layer rejects >1 source; guard defensively without
+            // echoing any value.
+            (Some(_), Some(_)) => {
+                return Err(error::base_error(format!(
+                    "secret {name:?}: \"env\" and \"store\" are mutually exclusive"
+                )))
+            }
+        };
+        out.push(SecretModificationPatch {
+            name,
+            source,
+            value: value.unwrap_or_default().into(),
+            placeholder: conv::opt_string(h, "placeholder")?,
+            allowed_hosts: conv::opt_string_vec(h, "allowed_hosts")?,
+        });
+    }
+    Ok(out)
+}
+
+/// Apply the parsed `policy` string to a modify builder. `no_restart` (default)
+/// leaves the builder untouched; `next_start`/`restart` select those policies.
+fn apply_modify_policy(
+    builder: SandboxModificationBuilder,
+    policy: &str,
+) -> Result<SandboxModificationBuilder, Error> {
+    match policy {
+        "no_restart" => Ok(builder),
+        "next_start" => Ok(builder.next_start()),
+        "restart" => Ok(builder.restart()),
+        other => Err(error::base_error(format!(
+            "unknown policy {other:?}; expected \"no_restart\", \"next_start\", or \"restart\""
+        ))),
+    }
+}
+
 //--------------------------------------------------------------------------------------------------
 // Pull progress (streaming image-pull during create_with_progress)
 //--------------------------------------------------------------------------------------------------
@@ -1987,6 +2153,27 @@ impl SbHandle {
         let snap = block_on(self.inner.snapshot_to(path)).map_err(error::to_ruby)?;
         Ok(crate::snapshot::snapshot_to_hash(&snap))
     }
+
+    /// Health-check the guest agent without refreshing the idle timer. A stopped
+    /// sandbox raises `SandboxNotRunningError` (the handle does not start it
+    /// implicitly). Returns `{ name, latency_secs }`.
+    fn ping(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.ping()).map_err(error::to_ruby)?;
+        Ok(ping_result_to_hash(&result))
+    }
+
+    /// Explicitly refresh the idle-activity timer. A stopped sandbox raises
+    /// `SandboxNotRunningError`. Returns `{ name, activity_seq }`.
+    fn touch(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.touch()).map_err(error::to_ruby)?;
+        Ok(touch_result_to_hash(&result))
+    }
+
+    /// Plan or apply a live sandbox modification (see `Sandbox::modify`). Returns
+    /// the `SandboxModificationPlan` as a JSON string.
+    fn modify(&self, opts: RHash) -> Result<String, Error> {
+        run_modify(self.inner.modify(), opts)
+    }
 }
 
 //--------------------------------------------------------------------------------------------------
@@ -2100,6 +2287,9 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("owns_lifecycle", method!(Sandbox::owns_lifecycle, 0))?;
     class.define_method("detach", method!(Sandbox::detach, 0))?;
     class.define_method("metrics", method!(Sandbox::metrics, 0))?;
+    class.define_method("ping", method!(Sandbox::ping, 0))?;
+    class.define_method("touch", method!(Sandbox::touch, 0))?;
+    class.define_method("modify", method!(Sandbox::modify, 1))?;
     class.define_method("metrics_stream", method!(Sandbox::metrics_stream, 1))?;
     class.define_method("logs", method!(Sandbox::logs, 1))?;
     class.define_method("log_stream", method!(Sandbox::log_stream, 1))?;
@@ -2148,6 +2338,9 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     handle.define_method("config_json", method!(SbHandle::config_json, 0))?;
     handle.define_method("snapshot", method!(SbHandle::snapshot, 1))?;
     handle.define_method("snapshot_to", method!(SbHandle::snapshot_to, 1))?;
+    handle.define_method("ping", method!(SbHandle::ping, 0))?;
+    handle.define_method("touch", method!(SbHandle::touch, 0))?;
+    handle.define_method("modify", method!(SbHandle::modify, 1))?;
 
     let session = native.define_class("PullSession", ruby.class_object())?;
     session.define_method("recv", method!(PullSession::recv, 0))?;

data/lib/microsandbox/modification.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # The result of {Sandbox#ping} / {SandboxHandle#ping}: a lightweight health
+  # check that confirms the guest agent is reachable without refreshing the
+  # sandbox idle timer. Mirrors the official SDKs' `SandboxPingResult`.
+  #
+  # The native layer reports latency as seconds; {#latency} is the canonical
+  # value and {#latency_ms} the convenience the Python/Node SDKs expose.
+  class PingResult
+    # @return [String] the sandbox name that was pinged
+    attr_reader :name
+    # @return [Float] round-trip latency in seconds
+    attr_reader :latency
+
+    def initialize(data)
+      @name = data["name"]
+      @latency = data["latency_secs"]
+    end
+
+    # @return [Float] round-trip latency in milliseconds
+    def latency_ms
+      @latency * 1000.0
+    end
+
+    def inspect
+      "#<Microsandbox::PingResult name=#{@name.inspect} latency_ms=#{format("%.3f", latency_ms)}>"
+    end
+  end
+
+  # The result of {Sandbox#touch} / {SandboxHandle#touch}: an explicit refresh of
+  # the sandbox idle-activity timer. Mirrors the official SDKs' `SandboxTouchResult`.
+  class TouchResult
+    # @return [String] the sandbox name that was touched
+    attr_reader :name
+    # @return [Integer] the agent activity sequence after this touch was recorded
+    attr_reader :activity_seq
+
+    def initialize(data)
+      @name = data["name"]
+      @activity_seq = data["activity_seq"]
+    end
+
+    def inspect
+      "#<Microsandbox::TouchResult name=#{@name.inspect} activity_seq=#{@activity_seq}>"
+    end
+  end
+
+  # The plan produced by {Sandbox#modify} / {SandboxHandle#modify}: the classified
+  # set of changes a modification requested, and (for a non-dry-run apply) whether
+  # they were applied plus any live-resize convergence outcomes. Mirrors the
+  # official SDKs' `SandboxModificationPlan`.
+  #
+  # The nested collections ({#changes}, {#conflicts}, {#warnings},
+  # {#resize_status}) are frozen Arrays of frozen, symbol-keyed Hashes carrying
+  # the canonical snake_case fields verbatim (e.g. a config change is
+  # `{ kind: "config", field:, change:, before:, after:, disposition:, reason: }`;
+  # a secret change adds `name:`, `before_ref:`, `after_ref:`, `allow_hosts:`).
+  # Enum values stay as the runtime's strings (e.g. a `disposition` of
+  # `"next start"`, a `state` of `"guest-refused"`).
+  class ModificationPlan
+    # @return [String] the sandbox the plan applies to
+    attr_reader :sandbox
+    # @return [String] the sandbox status used to classify the changes
+    attr_reader :status
+    # @return [Symbol] :no_restart, :next_start, or :restart
+    attr_reader :policy
+    # @return [Array<Hash>] the planned changes (config and secret)
+    attr_reader :changes
+    # @return [Array<Hash>] conflicts that must be resolved before applying
+    attr_reader :conflicts
+    # @return [Array<Hash>] non-fatal warnings about the patch
+    attr_reader :warnings
+    # @return [Array<Hash>] live resource-resize outcomes (populated by an apply)
+    attr_reader :resize_status
+
+    def initialize(data)
+      @sandbox = data["sandbox"]
+      @status = data["status"]
+      @applied = data["applied"]
+      @policy = data["policy"]&.to_sym
+      @changes = freeze_items(data["changes"])
+      @conflicts = freeze_items(data["conflicts"])
+      @warnings = freeze_items(data["warnings"])
+      @resize_status = freeze_items(data["resize_status"])
+    end
+
+    # @return [Boolean] whether the changes were applied (false for a dry run)
+    def applied?
+      @applied
+    end
+
+    def inspect
+      "#<Microsandbox::ModificationPlan sandbox=#{@sandbox.inspect} applied=#{@applied} " \
+        "policy=#{@policy} changes=#{@changes.size} conflicts=#{@conflicts.size} " \
+        "warnings=#{@warnings.size}>"
+    end
+
+    private
+
+    # Convert a JSON array of plan entries (string-keyed Hashes) into a frozen
+    # Array of frozen, symbol-keyed Hashes. The entries are shallow (all values
+    # are scalars or string arrays), so a single `transform_keys` suffices.
+    def freeze_items(items)
+      Array(items).map { |item| item.transform_keys(&:to_sym).freeze }.freeze
+    end
+  end
+end

data/lib/microsandbox/sandbox.rb

@@ -116,6 +116,30 @@ module Microsandbox
       JSON.parse(@native.config_json)
     end
 
+    # Health-check the guest agent without refreshing the idle timer. Connects
+    # to the running sandbox and sends `core.ping`; a stopped sandbox raises
+    # {SandboxNotRunningError} (it is not started implicitly). Mirrors the
+    # official SDKs' `ping`.
+    # @return [PingResult]
+    def ping
+      PingResult.new(@native.ping)
+    end
+
+    # Explicitly refresh this sandbox's idle-activity timer. A stopped sandbox
+    # raises {SandboxNotRunningError}. Mirrors the official SDKs' `touch`.
+    # @return [TouchResult]
+    def touch
+      TouchResult.new(@native.touch)
+    end
+
+    # Plan or apply a live modification of this sandbox. See {Sandbox#modify} for
+    # the full option set.
+    # @return [ModificationPlan]
+    def modify(**kwargs)
+      opts = Sandbox.send(:build_modify_opts, **kwargs)
+      ModificationPlan.new(JSON.parse(@native.modify(opts)))
+    end
+
     # Snapshot this (stopped) sandbox under a bare name, resolved under the
     # snapshots dir. Convenience equivalent of
     # `Snapshot.create(name, name: <snapshot-name>)` addressed by this handle.
@@ -213,7 +237,12 @@ module Microsandbox
       # @param name [String] sandbox name (max 128 UTF-8 bytes)
       # @param image [String, nil] OCI image reference (e.g. "python")
       # @param cpus [Integer, nil] number of vCPUs
+      # @param max_cpus [Integer, nil] boot-time maximum vCPU ceiling a later live
+      #   {Sandbox#modify} can grow up to (defaults to `cpus`; must be >= `cpus`)
       # @param memory [Integer, nil] memory in MiB
+      # @param max_memory [Integer, nil] boot-time maximum memory ceiling (MiB) a
+      #   later live {Sandbox#modify} can grow up to (defaults to `memory`; must
+      #   be >= `memory`)
       # @param env [Hash, nil] environment variables
       # @param workdir [String, nil] working directory inside the guest
       # @param shell [String, nil] default shell (for {#shell})
@@ -334,7 +363,8 @@ module Microsandbox
 
       # @api private
       # Shared keyword-option builder for {create}/{create_with_progress}.
-      def build_create_opts(image: nil, cpus: nil, memory: nil, env: nil, workdir: nil,
+      def build_create_opts(image: nil, cpus: nil, max_cpus: nil, memory: nil, max_memory: nil,
+        env: nil, workdir: nil,
         shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil,
         entrypoint: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil,
         dns: nil, tls: nil, ipv4_pool: nil, ipv6_pool: nil,
@@ -370,7 +400,9 @@ module Microsandbox
         opts["from_snapshot"] = from_snapshot.to_s if from_snapshot
         opts["fstype"] = fstype.to_s if fstype
         opts["cpus"] = Integer(cpus) if cpus
+        opts["max_cpus"] = Integer(max_cpus) if max_cpus
         opts["memory"] = Integer(memory) if memory
+        opts["max_memory"] = Integer(max_memory) if max_memory
         opts["workdir"] = workdir.to_s if workdir
         opts["shell"] = shell.to_s if shell
         opts["user"] = user.to_s if user
@@ -522,6 +554,99 @@ module Microsandbox
         Array(secrets).map { |spec| normalize_secret(spec) }
       end
 
+      # @api private
+      # Shared keyword-option builder for {Sandbox#modify}/{SandboxHandle#modify}.
+      # Produces the string-keyed Hash the native `modify` reads. `policy` is
+      # always set (defaulting to "no_restart"); everything else is included only
+      # when provided so an unset option means "leave unchanged".
+      def build_modify_opts(cpus: nil, max_cpus: nil, memory: nil, max_memory: nil,
+        env: nil, remove_env: nil, labels: nil, remove_labels: nil, workdir: nil,
+        secrets: nil, remove_secrets: nil, policy: nil, dry_run: false)
+        opts = {}
+        opts["cpus"] = Integer(cpus) if cpus
+        opts["max_cpus"] = Integer(max_cpus) if max_cpus
+        opts["memory"] = Integer(memory) if memory
+        opts["max_memory"] = Integer(max_memory) if max_memory
+        opts["env"] = stringify(env) if env
+        opts["remove_env"] = Array(remove_env).map(&:to_s) if remove_env
+        opts["labels"] = stringify(labels) if labels
+        opts["remove_labels"] = Array(remove_labels).map(&:to_s) if remove_labels
+        opts["workdir"] = workdir.to_s if workdir
+        opts["secrets"] = normalize_modify_secrets(secrets) if secrets
+        opts["remove_secrets"] = Array(remove_secrets).map(&:to_s) if remove_secrets
+        opts["policy"] = normalize_modify_policy(policy)
+        opts["dry_run"] = true if dry_run
+        opts
+      end
+
+      # Normalize the `secrets:` modify option — a Hash of `{ name => spec }` —
+      # into the native array of specs, sorted by name for deterministic patch
+      # (and plan) ordering. The modify secret vocabulary differs from create's
+      # (source-or-value with `env:`/`store:`/`value:` mutually exclusive, keyed
+      # by secret name), mirroring the upstream `SecretModifySpec`.
+      def normalize_modify_secrets(secrets)
+        unless secrets.is_a?(Hash)
+          raise ArgumentError, "secrets: must be a Hash of { name => spec } (got #{secrets.class})"
+        end
+        out = secrets.map { |name, spec| normalize_modify_secret(name, spec) }
+          .sort_by { |h| h["name"] }
+        # A Symbol and a String key stringify to the same secret name, yielding
+        # two same-name specs. Upstream's fluent API dedupes those; the patch
+        # path we drive does not, and duplicates make the live value and the
+        # persisted config diverge nondeterministically — reject them loudly.
+        dup = out.group_by { |h| h["name"] }.find { |_, specs| specs.size > 1 }
+        if dup
+          raise ArgumentError,
+            "secrets: duplicate entries for #{dup.first.inspect} (a Symbol and a String key stringify to the same name)"
+        end
+        out
+      end
+
+      def normalize_modify_secret(name, spec)
+        spec ||= {}
+        unless spec.is_a?(Hash)
+          # Reject before any spec access: a non-Hash spec (e.g. the tempting
+          # `{ name => raw_value }` shorthand) must never reach a method call
+          # whose NoMethodError would embed the receiver — cleartext — in the
+          # message on Ruby < 3.3.
+          raise ArgumentError,
+            "secret #{name.to_s.inspect}: spec must be a Hash (e.g. { value: ... } or { env: ... }), got #{spec.class}"
+        end
+        env = fetch_opt(spec, :env)
+        value = fetch_opt(spec, :value)
+        store = fetch_opt(spec, :store)
+        present = {"env" => env, "value" => value, "store" => store}.reject { |_, v| v.nil? }
+        if present.size > 1
+          # Report only the conflicting KEYS, never the values — a secret spec's
+          # :value is cleartext and error messages routinely land in logs and
+          # error trackers. Mirrors normalize_secret above.
+          keys = present.keys.map(&:inspect).join(" and ")
+          raise ArgumentError,
+            "secret #{name.to_s.inspect}: #{keys} are mutually exclusive; set at most one"
+        end
+        out = {"name" => name.to_s}
+        out["env"] = env.to_s if env
+        out["value"] = value.to_s if value
+        out["store"] = store.to_s if store
+        pl = fetch_opt(spec, :placeholder)
+        out["placeholder"] = pl.to_s if pl
+        hosts = spec[:allowed_hosts] || spec["allowed_hosts"]
+        out["allowed_hosts"] = Array(hosts).map(&:to_s) if hosts
+        out
+      end
+
+      # Normalize the `policy:` modify option (Symbol or String) to the native
+      # string, defaulting to "no_restart".
+      def normalize_modify_policy(policy)
+        return "no_restart" if policy.nil?
+        s = policy.to_s
+        unless %w[no_restart next_start restart].include?(s)
+          raise ArgumentError,
+            "policy: must be :no_restart, :next_start, or :restart (got #{policy.inspect})"
+        end
+        s
+      end
+
       def normalize_secret(spec)
         env = spec[:env] || spec["env"]
         value = spec[:value] || spec["value"]
@@ -941,6 +1066,57 @@ module Microsandbox
       Metrics.new(@native.metrics)
     end
 
+    # Health-check the guest agent without refreshing the idle timer. Sends
+    # `core.ping` to the running sandbox and reports the round-trip latency.
+    # Mirrors the official SDKs' `ping`.
+    # @return [PingResult]
+    def ping
+      PingResult.new(@native.ping)
+    end
+
+    # Explicitly refresh this sandbox's idle-activity timer (resetting any
+    # `idle_timeout:` countdown). Mirrors the official SDKs' `touch`.
+    # @return [TouchResult]
+    def touch
+      TouchResult.new(@native.touch)
+    end
+
+    # Plan or apply a live modification of this sandbox: resize CPU/memory,
+    # adjust env/labels/workdir, and rotate/remove secrets, without recreating
+    # the sandbox. The apply is all-or-nothing under the chosen `policy:`: the
+    # default `:no_restart` applies only changes that are live-capable *right
+    # now* and raises if any requested change needs a restart (on a running
+    # sandbox that includes env/labels/workdir and *adding* a secret — rotating
+    # or removing an existing one is live). Pass `policy: :next_start` to
+    # persist restart-required changes for the next start, or `:restart` to
+    # restart and apply them now; use `dry_run: true` to preview each change's
+    # disposition without applying anything. Mirrors the official SDKs'
+    # `modify`. Returns a {ModificationPlan} classifying each change.
+    #
+    # @param cpus [Integer, nil] desired effective vCPU count
+    # @param max_cpus [Integer, nil] desired boot-time maximum vCPU ceiling
+    # @param memory [Integer, nil] desired effective guest memory in MiB
+    # @param max_memory [Integer, nil] desired boot-time maximum memory (MiB)
+    # @param env [Hash, nil] environment variables to set for future execs
+    # @param remove_env [Array<String>, nil] environment variable names to remove
+    # @param labels [Hash, nil] labels to set
+    # @param remove_labels [Array<String>, nil] label keys to remove
+    # @param workdir [String, nil] desired working directory for future execs
+    # @param secrets [Hash, nil] desired secret specs keyed by secret name. Each
+    #   spec is a Hash with at most one of `env:` (host env var to read),
+    #   `store:` (host secret-store reference), or `value:` (raw material), plus
+    #   optional `placeholder:` and `allowed_hosts:` (Array of host patterns).
+    # @param remove_secrets [Array<String>, nil] secret names to remove
+    # @param policy [Symbol, String, nil] `:no_restart` (default — apply only
+    #   changes that need no restart), `:next_start` (persist for the next
+    #   start), or `:restart` (restart to apply restart-required changes)
+    # @param dry_run [Boolean] compute the plan without applying anything
+    # @return [ModificationPlan]
+    def modify(**kwargs)
+      opts = Sandbox.send(:build_modify_opts, **kwargs)
+      ModificationPlan.new(JSON.parse(@native.modify(opts)))
+    end
+
     # Read captured logs.
     #
     # @param tail [Integer, nil] only the last N entries

data/lib/microsandbox/version.rb

@@ -8,12 +8,12 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.9.1"
+  VERSION = "0.10.0"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in
   # ext/microsandbox/Cargo.toml. Exposed at runtime as
   # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
   # sync with the Cargo tag so it can't silently drift out of date.
-  RUNTIME_VERSION = "v0.6.2"
+  RUNTIME_VERSION = "v0.6.6"
 end

data/lib/microsandbox.rb

@@ -30,6 +30,7 @@ require_relative "microsandbox/patch"
 require_relative "microsandbox/network"
 require_relative "microsandbox/agent"
 require_relative "microsandbox/ssh"
+require_relative "microsandbox/modification"
 require_relative "microsandbox/sandbox"
 
 # Microsandbox — lightweight microVM sandboxes for Ruby.