feat(cua): add gated candidate install readiness

ci/source-architecture-budget.json

@@ -39,7 +39,8 @@
       "src/lib/actions/inference-set.ts": 32,
       "src/lib/actions/sandbox/connect.ts": 38,
       "src/lib/actions/sandbox/destroy.ts": 29,
-      "src/lib/actions/sandbox/doctor.ts": 29,
+      "src/lib/actions/sandbox/doctor.ts": 30,
+      "src/lib/actions/sandbox/status-snapshot.ts": 21,
       "src/lib/actions/sandbox/policy-channel.ts": 29,
       "src/lib/actions/sandbox/process-recovery.ts": 21,
       "src/lib/actions/sandbox/rebuild-pipeline.ts": 28,

package.json

@@ -122,6 +122,8 @@
     "nemoclaw-blueprint/",
     "managed-inference/",
     "schemas/network-policy.schema.json",
+    "schemas/cua-lifecycle.schema.json",
+    "schemas/cua-target-manifest.schema.json",
     "schemas/sandbox-policy.schema.json",
     "scripts/",
     "docs/resources/local-credential-form.html",

schemas/cua-lifecycle.schema.json

@@ -0,0 +1,192 @@
+{
+  "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/NVIDIA/NemoClaw/schemas/cua-lifecycle.schema.json",
+  "title": "NemoClaw CUA candidate lifecycle contract",
+  "description": "Credential-free serialized readiness for the private CUA candidate install-and-inspect slice.",
+  "$ref": "#/$defs/runtimeReadiness",
+  "$defs": {
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "safeId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]*$"
+    },
+    "safeModel": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?:/[A-Za-z0-9][A-Za-z0-9._-]{0,127}){0,7}$"
+    },
+    "component": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "digest", "owner"],
+      "properties": {
+        "name": { "$ref": "#/$defs/safeId" },
+        "version": { "$ref": "#/$defs/safeId" },
+        "digest": { "$ref": "#/$defs/digest" },
+        "owner": { "$ref": "#/$defs/safeId" }
+      }
+    },
+    "candidateQualification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "environmentDigest", "bundleReceiptDigest"],
+      "properties": {
+        "state": { "const": "candidate" },
+        "environmentDigest": { "$ref": "#/$defs/digest" },
+        "bundleReceiptDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "runtimeReadiness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "kind",
+        "agent",
+        "mode",
+        "status",
+        "sourceRevision",
+        "sourceClean",
+        "runtimeManifestDigest",
+        "providerAuthorityDigest",
+        "qualification",
+        "components",
+        "inference",
+        "appliedPolicy",
+        "commands",
+        "limits",
+        "requiredCapabilities",
+        "targetOperations",
+        "securityOperations",
+        "taskOperations"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "1.0.0" },
+        "kind": { "const": "runtime-readiness" },
+        "agent": { "const": "nemocua" },
+        "mode": { "const": "standalone" },
+        "status": { "enum": ["candidate", "unavailable", "incompatible"] },
+        "sourceRevision": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40}$"
+        },
+        "sourceClean": { "const": true },
+        "runtimeManifestDigest": { "$ref": "#/$defs/digest" },
+        "providerAuthorityDigest": { "$ref": "#/$defs/digest" },
+        "qualification": {
+          "oneOf": [
+            { "$ref": "#/$defs/candidateQualification" },
+            { "type": "null" }
+          ]
+        },
+        "components": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "openshell",
+            "runtime",
+            "sandboxImage",
+            "targetAdapter",
+            "policy",
+            "taskProtocol",
+            "securityVerifier"
+          ],
+          "properties": {
+            "openshell": { "$ref": "#/$defs/component" },
+            "runtime": { "$ref": "#/$defs/component" },
+            "sandboxImage": { "$ref": "#/$defs/component" },
+            "targetAdapter": { "$ref": "#/$defs/component" },
+            "policy": { "$ref": "#/$defs/component" },
+            "taskProtocol": { "$ref": "#/$defs/component" },
+            "securityVerifier": { "$ref": "#/$defs/component" }
+          }
+        },
+        "inference": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["provider", "model", "routeDigest"],
+          "properties": {
+            "provider": { "$ref": "#/$defs/safeId" },
+            "model": { "$ref": "#/$defs/safeModel" },
+            "routeDigest": { "$ref": "#/$defs/digest" }
+          }
+        },
+        "appliedPolicy": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["revision", "digest"],
+          "properties": {
+            "revision": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "digest": { "$ref": "#/$defs/digest" }
+          }
+        },
+        "commands": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["interactive", "headless", "version", "smoke"],
+          "properties": {
+            "interactive": { "const": true },
+            "headless": { "const": true },
+            "version": { "const": true },
+            "smoke": { "const": true }
+          }
+        },
+        "limits": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["targetsPerWorker", "activeTasksPerTarget"],
+          "properties": {
+            "targetsPerWorker": { "const": 1 },
+            "activeTasksPerTarget": { "const": 1 }
+          }
+        },
+        "requiredCapabilities": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "uniqueItems": true,
+          "items": { "enum": ["browser", "computer", "terminal"] }
+        },
+        "targetOperations": {
+          "type": "array",
+          "maxItems": 0
+        },
+        "securityOperations": {
+          "type": "array",
+          "maxItems": 0
+        },
+        "taskOperations": {
+          "type": "array",
+          "maxItems": 0
+        }
+      },
+      "oneOf": [
+        {
+          "required": ["status", "qualification"],
+          "properties": {
+            "status": { "const": "candidate" },
+            "qualification": { "$ref": "#/$defs/candidateQualification" }
+          }
+        },
+        {
+          "required": ["status", "qualification"],
+          "properties": {
+            "status": { "enum": ["unavailable", "incompatible"] },
+            "qualification": { "type": "null" }
+          }
+        }
+      ]
+    }
+  }
+}

schemas/cua-target-manifest.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/NVIDIA/NemoClaw/schemas/cua-target-manifest.schema.json",
+  "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0",
+  "title": "NemoClaw CUA target manifest",
+  "description": "Credential-free immutable identities in the private CUA candidate target bundle.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "identityDigest",
+    "platform",
+    "image",
+    "serviceBundle",
+    "capabilities"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^1\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"
+    },
+    "kind": {
+      "const": "target-manifest"
+    },
+    "identityDigest": {
+      "$ref": "#/$defs/digest"
+    },
+    "platform": {
+      "$ref": "#/$defs/safeSelector"
+    },
+    "image": {
+      "$ref": "#/$defs/componentIdentity"
+    },
+    "serviceBundle": {
+      "$ref": "#/$defs/componentIdentity"
+    },
+    "capabilities": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 3,
+      "items": {
+        "$ref": "#/$defs/capabilityIdentity"
+      }
+    }
+  },
+  "$defs": {
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "safeId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
+    "safeSelector": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$"
+    },
+    "componentIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "version",
+        "digest",
+        "owner"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/safeId"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "digest": {
+          "$ref": "#/$defs/digest"
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        }
+      }
+    },
+    "capabilityIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "protocolVersion"
+      ],
+      "properties": {
+        "id": {
+          "enum": [
+            "browser",
+            "computer",
+            "terminal"
+          ]
+        },
+        "protocolVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        }
+      }
+    }
+  }
+}

src/lib/actions/inference-get.ts

@@ -1,10 +1,9 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { captureOpenshell } from "../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../adapters/openshell/timeouts";
 import { sanitizeRouteValueForDisplay } from "../inference/config";
-import { getLiveGatewayInference } from "../inference/live";
+import { captureOpenshell, getLiveGatewayInference } from "../inference/live";
 
 export interface InferenceGetOptions {
   json?: boolean;

src/lib/actions/inference-set.ts

@@ -127,6 +127,7 @@ export interface InferenceSetDeps extends InferenceGatewayRestartDeps {
   getSandbox: (name: string) => SandboxEntry | null;
   listSandboxes: () => { sandboxes: SandboxEntry[]; defaultSandbox: string | null };
   updateSandbox: (name: string, updates: Partial<SandboxEntry>) => boolean;
+  updateSandboxInferenceRoute?: (name: string, updates: Partial<SandboxEntry>) => boolean;
   getRequestedAgent: () => string | null | undefined;
   loadSession: () => onboardSession.Session | null;
   updateSession: (
@@ -243,6 +244,7 @@ function defaultDeps(): InferenceSetDeps {
     getSandbox: registry.getSandbox,
     listSandboxes: registry.listSandboxes,
     updateSandbox: registry.updateSandbox,
+    updateSandboxInferenceRoute: registry.updateSandboxInferenceRoute,
     getRequestedAgent: () => process.env.NEMOCLAW_AGENT,
     loadSession: onboardSession.loadSession,
     updateSession: onboardSession.updateSession,
@@ -1130,7 +1132,7 @@ async function runInferenceSetWithoutHostLock(
         nimContainer: registryMetadata.nimContainer ?? null,
       });
     if (
-      !deps.updateSandbox(
+      !(deps.updateSandboxInferenceRoute ?? deps.updateSandbox)(
         sandboxName,
         registryFields(
           resolveAgentInferenceApi(
@@ -1164,7 +1166,12 @@ async function runInferenceSetWithoutHostLock(
     // Refresh the registry with config-derived API-family metadata before the
     // crash-prone in-sandbox sync (#3725/#3726). Explicit operator-supplied
     // metadata remains authoritative when present.
-    if (!deps.updateSandbox(sandboxName, registryFields(preferredInferenceApi))) {
+    if (
+      !(deps.updateSandboxInferenceRoute ?? deps.updateSandbox)(
+        sandboxName,
+        registryFields(preferredInferenceApi),
+      )
+    ) {
       throw new InferenceSetError(
         `Failed to update NemoClaw registry for sandbox '${sandboxName}'.`,
       );