feat(app-server): report and cancel runtime installation

codex-rs/Cargo.lock

@@ -2770,6 +2770,7 @@ dependencies = [
  "serde",
  "serde_json",
  "serial_test",
+ "sha2",
  "tempfile",
  "test-case",
  "thiserror 2.0.18",
@@ -2780,6 +2781,7 @@ dependencies = [
  "tracing",
  "uuid",
  "wiremock",
+ "zip 2.4.2",
 ]
 
 [[package]]

codex-rs/app-server-protocol/schema/json/ClientRequest.json

@@ -2765,6 +2765,82 @@
         }
       ]
     },
+    "RuntimeInstallManifestParams": {
+      "properties": {
+        "archiveName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "archiveSha256": {
+          "type": "string"
+        },
+        "archiveSizeBytes": {
+          "format": "uint64",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "archiveUrl": {
+          "type": "string"
+        },
+        "bundleFormatVersion": {
+          "format": "uint32",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "bundleVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "format": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "runtimeRootDirectoryName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "archiveSha256",
+        "archiveUrl"
+      ],
+      "type": "object"
+    },
+    "RuntimeInstallParams": {
+      "properties": {
+        "environmentId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "manifest": {
+          "$ref": "#/definitions/RuntimeInstallManifestParams"
+        },
+        "release": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "manifest",
+        "release"
+      ],
+      "type": "object"
+    },
     "SandboxMode": {
       "enum": [
         "read-only",
@@ -5309,6 +5385,53 @@
       "title": "Plugin/installRequest",
       "type": "object"
     },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "runtime/install"
+          ],
+          "title": "Runtime/installRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/RuntimeInstallParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Runtime/installRequest",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "runtime/install/cancel"
+          ],
+          "title": "Runtime/install/cancelRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "type": "null"
+        }
+      },
+      "required": [
+        "id",
+        "method"
+      ],
+      "title": "Runtime/install/cancelRequest",
+      "type": "object"
+    },
     {
       "properties": {
         "id": {

codex-rs/app-server-protocol/schema/json/ServerNotification.json

@@ -2946,6 +2946,51 @@
       },
       "type": "object"
     },
+    "RuntimeInstallProgressNotification": {
+      "properties": {
+        "bundleVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "downloadedBytes": {
+          "format": "uint64",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "phase": {
+          "$ref": "#/definitions/RuntimeInstallProgressPhase"
+        },
+        "totalBytes": {
+          "format": "uint64",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "phase"
+      ],
+      "type": "object"
+    },
+    "RuntimeInstallProgressPhase": {
+      "enum": [
+        "checking",
+        "downloading",
+        "verifying",
+        "extracting",
+        "validating",
+        "installed",
+        "configuring"
+      ],
+      "type": "string"
+    },
     "SandboxPolicy": {
       "oneOf": [
         {
@@ -5397,6 +5442,26 @@
       "title": "Skills/changedNotification",
       "type": "object"
     },
+    {
+      "properties": {
+        "method": {
+          "enum": [
+            "runtime/install/progress"
+          ],
+          "title": "Runtime/install/progressNotificationMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/RuntimeInstallProgressNotification"
+        }
+      },
+      "required": [
+        "method",
+        "params"
+      ],
+      "title": "Runtime/install/progressNotification",
+      "type": "object"
+    },
     {
       "properties": {
         "method": {
@@ -6546,4 +6611,4 @@
     }
   ],
   "title": "ServerNotification"
-}
+}

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json

@@ -1309,6 +1309,53 @@
           "title": "Plugin/installRequest",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "runtime/install"
+              ],
+              "title": "Runtime/installRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/RuntimeInstallParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Runtime/installRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "runtime/install/cancel"
+              ],
+              "title": "Runtime/install/cancelRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "type": "null"
+            }
+          },
+          "required": [
+            "id",
+            "method"
+          ],
+          "title": "Runtime/install/cancelRequest",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -4067,6 +4114,26 @@
           "title": "Skills/changedNotification",
           "type": "object"
         },
+        {
+          "properties": {
+            "method": {
+              "enum": [
+                "runtime/install/progress"
+              ],
+              "title": "Runtime/install/progressNotificationMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/RuntimeInstallProgressNotification"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "title": "Runtime/install/progressNotification",
+          "type": "object"
+        },
         {
           "properties": {
             "method": {
@@ -14613,6 +14680,221 @@
           }
         ]
       },
+      "RuntimeInstallCancelResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "properties": {
+          "status": {
+            "$ref": "#/definitions/v2/RuntimeInstallCancelStatus"
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "title": "RuntimeInstallCancelResponse",
+        "type": "object"
+      },
+      "RuntimeInstallCancelStatus": {
+        "enum": [
+          "canceled",
+          "not-found"
+        ],
+        "type": "string"
+      },
+      "RuntimeInstallManifestParams": {
+        "properties": {
+          "archiveName": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "archiveSha256": {
+            "type": "string"
+          },
+          "archiveSizeBytes": {
+            "format": "uint64",
+            "minimum": 0.0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "archiveUrl": {
+            "type": "string"
+          },
+          "bundleFormatVersion": {
+            "format": "uint32",
+            "minimum": 0.0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "bundleVersion": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "format": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "runtimeRootDirectoryName": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "archiveSha256",
+          "archiveUrl"
+        ],
+        "type": "object"
+      },
+      "RuntimeInstallParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "properties": {
+          "environmentId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "manifest": {
+            "$ref": "#/definitions/v2/RuntimeInstallManifestParams"
+          },
+          "release": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "manifest",
+          "release"
+        ],
+        "title": "RuntimeInstallParams",
+        "type": "object"
+      },
+      "RuntimeInstallPaths": {
+        "properties": {
+          "bundledPluginMarketplacePaths": {
+            "items": {
+              "$ref": "#/definitions/v2/AbsolutePathBuf"
+            },
+            "type": "array"
+          },
+          "bundledSkillPaths": {
+            "items": {
+              "$ref": "#/definitions/v2/AbsolutePathBuf"
+            },
+            "type": "array"
+          },
+          "nodeModulesPath": {
+            "$ref": "#/definitions/v2/AbsolutePathBuf"
+          },
+          "nodePath": {
+            "$ref": "#/definitions/v2/AbsolutePathBuf"
+          },
+          "pythonPath": {
+            "$ref": "#/definitions/v2/AbsolutePathBuf"
+          },
+          "skillsToRemove": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "bundledPluginMarketplacePaths",
+          "bundledSkillPaths",
+          "nodeModulesPath",
+          "nodePath",
+          "pythonPath",
+          "skillsToRemove"
+        ],
+        "type": "object"
+      },
+      "RuntimeInstallProgressNotification": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "properties": {
+          "bundleVersion": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "downloadedBytes": {
+            "format": "uint64",
+            "minimum": 0.0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "phase": {
+            "$ref": "#/definitions/v2/RuntimeInstallProgressPhase"
+          },
+          "totalBytes": {
+            "format": "uint64",
+            "minimum": 0.0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "phase"
+        ],
+        "title": "RuntimeInstallProgressNotification",
+        "type": "object"
+      },
+      "RuntimeInstallProgressPhase": {
+        "enum": [
+          "checking",
+          "downloading",
+          "verifying",
+          "extracting",
+          "validating",
+          "installed",
+          "configuring"
+        ],
+        "type": "string"
+      },
+      "RuntimeInstallResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "properties": {
+          "bundleVersion": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "paths": {
+            "$ref": "#/definitions/v2/RuntimeInstallPaths"
+          },
+          "status": {
+            "$ref": "#/definitions/v2/RuntimeInstallStatus"
+          }
+        },
+        "required": [
+          "paths",
+          "status"
+        ],
+        "title": "RuntimeInstallResponse",
+        "type": "object"
+      },
+      "RuntimeInstallStatus": {
+        "enum": [
+          "already-current",
+          "installed"
+        ],
+        "type": "string"
+      },
       "SandboxMode": {
         "enum": [
           "read-only",

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json

@@ -2035,6 +2035,53 @@
           "title": "Plugin/installRequest",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "runtime/install"
+              ],
+              "title": "Runtime/installRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/RuntimeInstallParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Runtime/installRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "runtime/install/cancel"
+              ],
+              "title": "Runtime/install/cancelRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "type": "null"
+            }
+          },
+          "required": [
+            "id",
+            "method"
+          ],
+          "title": "Runtime/install/cancelRequest",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -11142,6 +11189,221 @@
         }
       ]
     },
+    "RuntimeInstallCancelResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "properties": {
+        "status": {
+          "$ref": "#/definitions/RuntimeInstallCancelStatus"
+        }
+      },
+      "required": [
+        "status"
+      ],
+      "title": "RuntimeInstallCancelResponse",
+      "type": "object"
+    },
+    "RuntimeInstallCancelStatus": {
+      "enum": [
+        "canceled",
+        "not-found"
+      ],
+      "type": "string"
+    },
+    "RuntimeInstallManifestParams": {
+      "properties": {
+        "archiveName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "archiveSha256": {
+          "type": "string"
+        },
+        "archiveSizeBytes": {
+          "format": "uint64",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "archiveUrl": {
+          "type": "string"
+        },
+        "bundleFormatVersion": {
+          "format": "uint32",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "bundleVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "format": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "runtimeRootDirectoryName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "archiveSha256",
+        "archiveUrl"
+      ],
+      "type": "object"
+    },
+    "RuntimeInstallParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "properties": {
+        "environmentId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "manifest": {
+          "$ref": "#/definitions/RuntimeInstallManifestParams"
+        },
+        "release": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "manifest",
+        "release"
+      ],
+      "title": "RuntimeInstallParams",
+      "type": "object"
+    },
+    "RuntimeInstallPaths": {
+      "properties": {
+        "bundledPluginMarketplacePaths": {
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          },
+          "type": "array"
+        },
+        "bundledSkillPaths": {
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          },
+          "type": "array"
+        },
+        "nodeModulesPath": {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        },
+        "nodePath": {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        },
+        "pythonPath": {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        },
+        "skillsToRemove": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "bundledPluginMarketplacePaths",
+        "bundledSkillPaths",
+        "nodeModulesPath",
+        "nodePath",
+        "pythonPath",
+        "skillsToRemove"
+      ],
+      "type": "object"
+    },
+    "RuntimeInstallProgressNotification": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "properties": {
+        "bundleVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "downloadedBytes": {
+          "format": "uint64",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "phase": {
+          "$ref": "#/definitions/RuntimeInstallProgressPhase"
+        },
+        "totalBytes": {
+          "format": "uint64",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "phase"
+      ],
+      "title": "RuntimeInstallProgressNotification",
+      "type": "object"
+    },
+    "RuntimeInstallProgressPhase": {
+      "enum": [
+        "checking",
+        "downloading",
+        "verifying",
+        "extracting",
+        "validating",
+        "installed",
+        "configuring"
+      ],
+      "type": "string"
+    },
+    "RuntimeInstallResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "properties": {
+        "bundleVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "paths": {
+          "$ref": "#/definitions/RuntimeInstallPaths"
+        },
+        "status": {
+          "$ref": "#/definitions/RuntimeInstallStatus"
+        }
+      },
+      "required": [
+        "paths",
+        "status"
+      ],
+      "title": "RuntimeInstallResponse",
+      "type": "object"
+    },
+    "RuntimeInstallStatus": {
+      "enum": [
+        "already-current",
+        "installed"
+      ],
+      "type": "string"
+    },
     "SandboxMode": {
       "enum": [
         "read-only",
@@ -11444,6 +11706,26 @@
           "title": "Skills/changedNotification",
           "type": "object"
         },
+        {
+          "properties": {
+            "method": {
+              "enum": [
+                "runtime/install/progress"
+              ],
+              "title": "Runtime/install/progressNotificationMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/RuntimeInstallProgressNotification"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "title": "Runtime/install/progressNotification",
+          "type": "object"
+        },
         {
           "properties": {
             "method": {

codex-rs/app-server-protocol/schema/json/v2/RuntimeInstallCancelResponse.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "RuntimeInstallCancelStatus": {
+      "enum": [
+        "canceled",
+        "not-found"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "status": {
+      "$ref": "#/definitions/RuntimeInstallCancelStatus"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "title": "RuntimeInstallCancelResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/RuntimeInstallParams.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "RuntimeInstallManifestParams": {
+      "properties": {
+        "archiveName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "archiveSha256": {
+          "type": "string"
+        },
+        "archiveSizeBytes": {
+          "format": "uint64",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "archiveUrl": {
+          "type": "string"
+        },
+        "bundleFormatVersion": {
+          "format": "uint32",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "bundleVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "format": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "runtimeRootDirectoryName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "archiveSha256",
+        "archiveUrl"
+      ],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "environmentId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "manifest": {
+      "$ref": "#/definitions/RuntimeInstallManifestParams"
+    },
+    "release": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "manifest",
+    "release"
+  ],
+  "title": "RuntimeInstallParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/RuntimeInstallProgressNotification.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "RuntimeInstallProgressPhase": {
+      "enum": [
+        "checking",
+        "downloading",
+        "verifying",
+        "extracting",
+        "validating",
+        "installed",
+        "configuring"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "bundleVersion": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "downloadedBytes": {
+      "format": "uint64",
+      "minimum": 0.0,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "phase": {
+      "$ref": "#/definitions/RuntimeInstallProgressPhase"
+    },
+    "totalBytes": {
+      "format": "uint64",
+      "minimum": 0.0,
+      "type": [
+        "integer",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "phase"
+  ],
+  "title": "RuntimeInstallProgressNotification",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/RuntimeInstallResponse.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    },
+    "RuntimeInstallPaths": {
+      "properties": {
+        "bundledPluginMarketplacePaths": {
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          },
+          "type": "array"
+        },
+        "bundledSkillPaths": {
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          },
+          "type": "array"
+        },
+        "nodeModulesPath": {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        },
+        "nodePath": {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        },
+        "pythonPath": {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        },
+        "skillsToRemove": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "bundledPluginMarketplacePaths",
+        "bundledSkillPaths",
+        "nodeModulesPath",
+        "nodePath",
+        "pythonPath",
+        "skillsToRemove"
+      ],
+      "type": "object"
+    },
+    "RuntimeInstallStatus": {
+      "enum": [
+        "already-current",
+        "installed"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "bundleVersion": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "paths": {
+      "$ref": "#/definitions/RuntimeInstallPaths"
+    },
+    "status": {
+      "$ref": "#/definitions/RuntimeInstallStatus"
+    }
+  },
+  "required": [
+    "paths",
+    "status"
+  ],
+  "title": "RuntimeInstallResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallCancelResponse.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { RuntimeInstallCancelStatus } from "./RuntimeInstallCancelStatus";
+
+export type RuntimeInstallCancelResponse = { status: RuntimeInstallCancelStatus, };

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallCancelStatus.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type RuntimeInstallCancelStatus = "canceled" | "not-found";

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallManifestParams.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type RuntimeInstallManifestParams = { archiveName?: string | null, archiveSha256: string, archiveSizeBytes?: bigint | null, archiveUrl: string, bundleFormatVersion?: number | null, bundleVersion?: string | null, format?: string | null, runtimeRootDirectoryName?: string | null, };

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallParams.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { RuntimeInstallManifestParams } from "./RuntimeInstallManifestParams";
+
+export type RuntimeInstallParams = { environmentId?: string | null, manifest: RuntimeInstallManifestParams, release: string, };

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallPaths.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+export type RuntimeInstallPaths = { bundledPluginMarketplacePaths: Array<AbsolutePathBuf>, bundledSkillPaths: Array<AbsolutePathBuf>, nodeModulesPath: AbsolutePathBuf, nodePath: AbsolutePathBuf, pythonPath: AbsolutePathBuf, skillsToRemove: Array<string>, };

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallProgressNotification.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { RuntimeInstallProgressPhase } from "./RuntimeInstallProgressPhase";
+
+export type RuntimeInstallProgressNotification = { bundleVersion: string | null, downloadedBytes: bigint | null, phase: RuntimeInstallProgressPhase, totalBytes: bigint | null, };

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallProgressPhase.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type RuntimeInstallProgressPhase = "checking" | "downloading" | "verifying" | "extracting" | "validating" | "installed" | "configuring";

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallResponse.ts

@@ -0,0 +1,7 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { RuntimeInstallPaths } from "./RuntimeInstallPaths";
+import type { RuntimeInstallStatus } from "./RuntimeInstallStatus";
+
+export type RuntimeInstallResponse = { bundleVersion: string | null, paths: RuntimeInstallPaths, status: RuntimeInstallStatus, };

codex-rs/app-server-protocol/schema/typescript/v2/RuntimeInstallStatus.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type RuntimeInstallStatus = "already-current" | "installed";

codex-rs/app-server-protocol/schema/typescript/v2/index.ts

@@ -325,6 +325,15 @@ export type { ReviewDelivery } from "./ReviewDelivery";
 export type { ReviewStartParams } from "./ReviewStartParams";
 export type { ReviewStartResponse } from "./ReviewStartResponse";
 export type { ReviewTarget } from "./ReviewTarget";
+export type { RuntimeInstallCancelResponse } from "./RuntimeInstallCancelResponse";
+export type { RuntimeInstallCancelStatus } from "./RuntimeInstallCancelStatus";
+export type { RuntimeInstallManifestParams } from "./RuntimeInstallManifestParams";
+export type { RuntimeInstallParams } from "./RuntimeInstallParams";
+export type { RuntimeInstallPaths } from "./RuntimeInstallPaths";
+export type { RuntimeInstallProgressNotification } from "./RuntimeInstallProgressNotification";
+export type { RuntimeInstallProgressPhase } from "./RuntimeInstallProgressPhase";
+export type { RuntimeInstallResponse } from "./RuntimeInstallResponse";
+export type { RuntimeInstallStatus } from "./RuntimeInstallStatus";
 export type { SandboxMode } from "./SandboxMode";
 export type { SandboxPolicy } from "./SandboxPolicy";
 export type { SandboxWorkspaceWrite } from "./SandboxWorkspaceWrite";

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -737,6 +737,16 @@ client_request_definitions! {
         serialization: global("config"),
         response: v2::PluginInstallResponse,
     },
+    RuntimeInstall => "runtime/install" {
+        params: v2::RuntimeInstallParams,
+        serialization: global("runtime-install"),
+        response: v2::RuntimeInstallResponse,
+    },
+    RuntimeInstallCancel => "runtime/install/cancel" {
+        params: #[ts(type = "undefined")] #[serde(skip_serializing_if = "Option::is_none")] Option<()>,
+        serialization: None,
+        response: v2::RuntimeInstallCancelResponse,
+    },
     PluginUninstall => "plugin/uninstall" {
         params: v2::PluginUninstallParams,
         serialization: global("config"),
@@ -1475,6 +1485,7 @@ server_notification_definitions! {
     ThreadUnarchived => "thread/unarchived" (v2::ThreadUnarchivedNotification),
     ThreadClosed => "thread/closed" (v2::ThreadClosedNotification),
     SkillsChanged => "skills/changed" (v2::SkillsChangedNotification),
+    RuntimeInstallProgress => "runtime/install/progress" (v2::RuntimeInstallProgressNotification),
     ThreadNameUpdated => "thread/name/updated" (v2::ThreadNameUpdatedNotification),
     ThreadGoalUpdated => "thread/goal/updated" (v2::ThreadGoalUpdatedNotification),
     ThreadGoalCleared => "thread/goal/cleared" (v2::ThreadGoalClearedNotification),

codex-rs/app-server-protocol/src/protocol/v2/mod.rs

@@ -21,6 +21,7 @@ mod process;
 mod realtime;
 mod remote_control;
 mod review;
+mod runtime;
 mod thread;
 mod thread_data;
 mod turn;
@@ -47,6 +48,7 @@ pub use process::*;
 pub use realtime::*;
 pub use remote_control::*;
 pub use review::*;
+pub use runtime::*;
 pub use shared::*;
 pub use thread::*;
 pub use thread_data::*;

codex-rs/app-server-protocol/src/protocol/v2/runtime.rs

@@ -0,0 +1,102 @@
+use codex_utils_absolute_path::AbsolutePathBuf;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use ts_rs::TS;
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct RuntimeInstallManifestParams {
+    #[ts(optional = nullable)]
+    pub archive_name: Option<String>,
+    pub archive_sha256: String,
+    #[ts(optional = nullable)]
+    pub archive_size_bytes: Option<u64>,
+    pub archive_url: String,
+    #[ts(optional = nullable)]
+    pub bundle_format_version: Option<u32>,
+    #[ts(optional = nullable)]
+    pub bundle_version: Option<String>,
+    #[ts(optional = nullable)]
+    pub format: Option<String>,
+    #[ts(optional = nullable)]
+    pub runtime_root_directory_name: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct RuntimeInstallParams {
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
+    pub manifest: Box<RuntimeInstallManifestParams>,
+    pub release: String,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "kebab-case")]
+#[ts(export_to = "v2/")]
+pub enum RuntimeInstallCancelStatus {
+    Canceled,
+    NotFound,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct RuntimeInstallCancelResponse {
+    pub status: RuntimeInstallCancelStatus,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "kebab-case")]
+#[ts(export_to = "v2/")]
+pub enum RuntimeInstallStatus {
+    AlreadyCurrent,
+    Installed,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct RuntimeInstallPaths {
+    pub bundled_plugin_marketplace_paths: Vec<AbsolutePathBuf>,
+    pub bundled_skill_paths: Vec<AbsolutePathBuf>,
+    pub node_modules_path: AbsolutePathBuf,
+    pub node_path: AbsolutePathBuf,
+    pub python_path: AbsolutePathBuf,
+    pub skills_to_remove: Vec<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct RuntimeInstallResponse {
+    pub bundle_version: Option<String>,
+    pub paths: RuntimeInstallPaths,
+    pub status: RuntimeInstallStatus,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "kebab-case")]
+#[ts(export_to = "v2/")]
+pub enum RuntimeInstallProgressPhase {
+    Checking,
+    Downloading,
+    Verifying,
+    Extracting,
+    Validating,
+    Installed,
+    Configuring,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct RuntimeInstallProgressNotification {
+    pub bundle_version: Option<String>,
+    pub downloaded_bytes: Option<u64>,
+    pub phase: RuntimeInstallProgressPhase,
+    pub total_bytes: Option<u64>,
+}

codex-rs/app-server/README.md

@@ -212,6 +212,9 @@ Example with notification opt-out:
 - `remoteControl/status/changed` — notification emitted when the remote-control status or client-visible environment id changes. `status` is one of `disabled`, `connecting`, `connected`, or `errored`; `serverName` is the local machine name used by this app-server process; `environmentId` is a string when the app-server has a current enrollment and `null` when that enrollment is cleared, invalidated, or remote control is disabled. Newly initialized app-server clients always receive the current status snapshot.
 - `skills/config/write` — write user-level skill config by name or absolute path.
 - `plugin/install` — install a plugin from a discovered marketplace entry, rejecting marketplace entries marked unavailable for install, install MCPs if any, and return the effective plugin auth policy plus any apps that still need auth (**under development; do not call from production clients yet**).
+- `runtime/install` — install the selected primary runtime bundle and return its executable, dependency, bundled-skill, and bundled-marketplace paths after app-server config synchronization. Runtime installs are process-wide and serialized.
+- `runtime/install/progress` — notification sent to the connection that requested `runtime/install` as the active install moves through checking, downloading, verifying, extracting, validating, installed, and configuring phases. Download notifications include byte counts when available.
+- `runtime/install/cancel` — cancel the one active `runtime/install` request for this app-server process and report whether an install was found.
 - `plugin/uninstall` — uninstall a local plugin by `pluginId` in `<plugin>@<marketplace>` form by removing its cached files and clearing its user-level config entry, or uninstall a remote ChatGPT plugin by backend `pluginId` by forwarding the uninstall to the ChatGPT plugin backend and removing any downloaded remote-plugin cache (**under development; do not call from production clients yet**).
 - `mcpServer/oauth/login` — start an OAuth login for a configured MCP server; returns an `authorization_url` and later emits `mcpServer/oauthLogin/completed` once the browser flow finishes.
 - `tool/requestUserInput` — prompt the user with 1–3 short questions for a tool call and return their answers (experimental).

codex-rs/app-server/src/lib.rs

@@ -95,6 +95,7 @@ mod models;
 mod outgoing_message;
 mod request_processors;
 mod request_serialization;
+mod runtime_install;
 mod server_request_error;
 mod skills_watcher;
 mod thread_state;

codex-rs/app-server/src/message_processor.rs

@@ -31,6 +31,7 @@ use crate::request_processors::McpRequestProcessor;
 use crate::request_processors::PluginRequestProcessor;
 use crate::request_processors::ProcessExecRequestProcessor;
 use crate::request_processors::RemoteControlRequestProcessor;
+use crate::request_processors::RuntimeInstallRequestProcessor;
 use crate::request_processors::SearchRequestProcessor;
 use crate::request_processors::ThreadGoalRequestProcessor;
 use crate::request_processors::ThreadRequestProcessor;
@@ -177,6 +178,7 @@ pub(crate) struct MessageProcessor {
     mcp_processor: McpRequestProcessor,
     plugin_processor: PluginRequestProcessor,
     remote_control_processor: RemoteControlRequestProcessor,
+    runtime_install_processor: RuntimeInstallRequestProcessor,
     search_processor: SearchRequestProcessor,
     thread_goal_processor: ThreadGoalRequestProcessor,
     thread_processor: ThreadRequestProcessor,
@@ -402,6 +404,11 @@ impl MessageProcessor {
             workspace_settings_cache,
         );
         let remote_control_processor = RemoteControlRequestProcessor::new(remote_control_handle);
+        let runtime_install_processor = RuntimeInstallRequestProcessor::new(
+            Arc::clone(&environment_manager_for_requests),
+            outgoing.clone(),
+            Arc::clone(&thread_manager),
+        );
         let search_processor = SearchRequestProcessor::new(outgoing.clone());
         let thread_goal_processor = ThreadGoalRequestProcessor::new(
             Arc::clone(&thread_manager),
@@ -498,6 +505,7 @@ impl MessageProcessor {
             mcp_processor,
             plugin_processor,
             remote_control_processor,
+            runtime_install_processor,
             search_processor,
             thread_goal_processor,
             thread_processor,
@@ -968,6 +976,16 @@ impl MessageProcessor {
                 .model_provider_capabilities_read()
                 .await
                 .map(|response| Some(response.into())),
+            ClientRequest::RuntimeInstall { params, .. } => {
+                self.runtime_install_processor
+                    .install_runtime(connection_id, params)
+                    .await
+            }
+            ClientRequest::RuntimeInstallCancel { .. } => {
+                self.runtime_install_processor
+                    .cancel_runtime_install()
+                    .await
+            }
             ClientRequest::ThreadStart { params, .. } => {
                 self.thread_processor
                     .thread_start(

codex-rs/app-server/src/request_processors.rs

@@ -466,6 +466,7 @@ mod mcp_processor;
 mod plugins;
 mod process_exec_processor;
 mod remote_control_processor;
+mod runtime_install_processor;
 mod search;
 mod thread_processor;
 mod token_usage_replay;
@@ -488,6 +489,7 @@ pub(crate) use mcp_processor::McpRequestProcessor;
 pub(crate) use plugins::PluginRequestProcessor;
 pub(crate) use process_exec_processor::ProcessExecRequestProcessor;
 pub(crate) use remote_control_processor::RemoteControlRequestProcessor;
+pub(crate) use runtime_install_processor::RuntimeInstallRequestProcessor;
 pub(crate) use search::SearchRequestProcessor;
 pub(crate) use thread_goal_processor::ThreadGoalRequestProcessor;
 pub(crate) use thread_processor::ThreadRequestProcessor;

codex-rs/app-server/src/request_processors/runtime_install_processor.rs

@@ -0,0 +1,152 @@
+use super::*;
+use codex_app_server_protocol::RuntimeInstallCancelResponse;
+use codex_app_server_protocol::RuntimeInstallCancelStatus;
+use codex_app_server_protocol::RuntimeInstallParams;
+use codex_app_server_protocol::RuntimeInstallProgressNotification;
+use codex_app_server_protocol::RuntimeInstallProgressPhase;
+use std::sync::Mutex as StdMutex;
+
+#[derive(Clone)]
+pub(crate) struct RuntimeInstallRequestProcessor {
+    environment_manager: Arc<EnvironmentManager>,
+    outgoing: Arc<OutgoingMessageSender>,
+    thread_manager: Arc<ThreadManager>,
+    active_install: Arc<StdMutex<Option<CancellationToken>>>,
+}
+
+impl RuntimeInstallRequestProcessor {
+    pub(crate) fn new(
+        environment_manager: Arc<EnvironmentManager>,
+        outgoing: Arc<OutgoingMessageSender>,
+        thread_manager: Arc<ThreadManager>,
+    ) -> Self {
+        Self {
+            environment_manager,
+            outgoing,
+            thread_manager,
+            active_install: Arc::new(StdMutex::new(None)),
+        }
+    }
+
+    pub(crate) async fn install_runtime(
+        &self,
+        connection_id: ConnectionId,
+        mut params: RuntimeInstallParams,
+    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError> {
+        let (cancellation, _active_install) = self.begin_install()?;
+        let environment = if let Some(environment_id) = params.environment_id.take() {
+            self.environment_manager
+                .get_environment(&environment_id)
+                .ok_or_else(|| {
+                    invalid_request(format!(
+                        "unknown runtime install environment id `{environment_id}`"
+                    ))
+                })?
+        } else {
+            self.environment_manager
+                .default_or_local_environment()
+                .ok_or_else(|| internal_error("runtime install environment is not configured"))?
+        };
+
+        let (progress_tx, mut progress_rx) = tokio::sync::mpsc::unbounded_channel();
+        let outgoing = Arc::clone(&self.outgoing);
+        let progress_forwarder = tokio::spawn(async move {
+            while let Some(progress) = progress_rx.recv().await {
+                outgoing
+                    .send_server_notification_to_connections(
+                        &[connection_id],
+                        ServerNotification::RuntimeInstallProgress(progress),
+                    )
+                    .await;
+            }
+        });
+
+        let install_result = environment
+            .install_runtime_with_progress(params, progress_tx, cancellation)
+            .await;
+        if let Err(error) = progress_forwarder.await {
+            warn!("runtime install progress forwarder failed: {error}");
+        }
+
+        let response = install_result?;
+        self.send_progress(
+            connection_id,
+            RuntimeInstallProgressNotification {
+                bundle_version: response.bundle_version.clone(),
+                downloaded_bytes: None,
+                phase: RuntimeInstallProgressPhase::Configuring,
+                total_bytes: None,
+            },
+        )
+        .await;
+        let response =
+            crate::runtime_install::finalize_runtime_install(&environment, response).await?;
+        self.thread_manager.plugins_manager().clear_cache();
+        self.thread_manager.skills_manager().clear_cache();
+        Ok(Some(response.into()))
+    }
+
+    pub(crate) async fn cancel_runtime_install(
+        &self,
+    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError> {
+        let status = {
+            let active_install = self.active_install();
+            match active_install.as_ref() {
+                Some(cancellation) => {
+                    cancellation.cancel();
+                    RuntimeInstallCancelStatus::Canceled
+                }
+                None => RuntimeInstallCancelStatus::NotFound,
+            }
+        };
+        Ok(Some(RuntimeInstallCancelResponse { status }.into()))
+    }
+
+    fn begin_install(&self) -> Result<(CancellationToken, ActiveInstallGuard), JSONRPCErrorError> {
+        let cancellation = CancellationToken::new();
+        let mut active_install = self.active_install();
+        if active_install.is_some() {
+            return Err(invalid_request("runtime install is already in progress"));
+        }
+        *active_install = Some(cancellation.clone());
+        drop(active_install);
+        Ok((
+            cancellation,
+            ActiveInstallGuard {
+                active_install: Arc::clone(&self.active_install),
+            },
+        ))
+    }
+
+    fn active_install(&self) -> std::sync::MutexGuard<'_, Option<CancellationToken>> {
+        self.active_install
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+    }
+
+    async fn send_progress(
+        &self,
+        connection_id: ConnectionId,
+        progress: RuntimeInstallProgressNotification,
+    ) {
+        self.outgoing
+            .send_server_notification_to_connections(
+                &[connection_id],
+                ServerNotification::RuntimeInstallProgress(progress),
+            )
+            .await;
+    }
+}
+
+struct ActiveInstallGuard {
+    active_install: Arc<StdMutex<Option<CancellationToken>>>,
+}
+
+impl Drop for ActiveInstallGuard {
+    fn drop(&mut self) {
+        self.active_install
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .take();
+    }
+}

codex-rs/app-server/src/runtime_install.rs

@@ -0,0 +1,655 @@
+use std::ffi::OsStr;
+use std::io;
+use std::path::Component;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::RuntimeInstallPaths;
+use codex_app_server_protocol::RuntimeInstallResponse;
+use codex_exec_server::CopyOptions;
+use codex_exec_server::CreateDirectoryOptions;
+use codex_exec_server::Environment;
+use codex_exec_server::ExecutorFileSystem;
+use codex_exec_server::RemoveOptions;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use uuid::Uuid;
+
+use crate::error_code::internal_error;
+use crate::error_code::invalid_params;
+
+const PUBLISHED_ARTIFACT_NAME: &str = "codex-primary-runtime";
+
+pub(crate) async fn finalize_runtime_install(
+    environment: &Environment,
+    mut response: RuntimeInstallResponse,
+) -> Result<RuntimeInstallResponse, JSONRPCErrorError> {
+    if response.paths.bundled_plugin_marketplace_paths.is_empty()
+        && response.paths.bundled_skill_paths.is_empty()
+        && response.paths.skills_to_remove.is_empty()
+    {
+        return Ok(response);
+    }
+
+    let codex_home = environment.codex_home().await?;
+    response.paths =
+        finalize_runtime_paths(environment.get_filesystem(), &codex_home, response.paths).await?;
+    Ok(response)
+}
+
+async fn finalize_runtime_paths(
+    fs: Arc<dyn ExecutorFileSystem>,
+    codex_home: &AbsolutePathBuf,
+    mut paths: RuntimeInstallPaths,
+) -> Result<RuntimeInstallPaths, JSONRPCErrorError> {
+    paths.bundled_plugin_marketplace_paths = materialize_bundled_plugin_marketplaces(
+        Arc::clone(&fs),
+        codex_home,
+        &paths.bundled_plugin_marketplace_paths,
+    )
+    .await?;
+    paths.bundled_skill_paths = sync_primary_runtime_skills(
+        fs,
+        codex_home,
+        &paths.bundled_skill_paths,
+        &paths.skills_to_remove,
+    )
+    .await?;
+    Ok(paths)
+}
+
+async fn materialize_bundled_plugin_marketplaces(
+    fs: Arc<dyn ExecutorFileSystem>,
+    codex_home: &AbsolutePathBuf,
+    marketplace_roots: &[AbsolutePathBuf],
+) -> Result<Vec<AbsolutePathBuf>, JSONRPCErrorError> {
+    if marketplace_roots.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let destination_root = absolute_path(
+        codex_home
+            .as_path()
+            .join("plugins")
+            .join(PUBLISHED_ARTIFACT_NAME)
+            .join("marketplaces"),
+    )?;
+    let mut materialized = Vec::with_capacity(marketplace_roots.len());
+    for marketplace_root in marketplace_roots {
+        let marketplace_name = marketplace_root.as_path().file_name().ok_or_else(|| {
+            invalid_params("bundled plugin marketplace path has no directory name")
+        })?;
+        let destination = absolute_path(
+            destination_root
+                .as_path()
+                .join(safe_path_segment(marketplace_name)),
+        )?;
+        replace_directory(Arc::clone(&fs), marketplace_root, &destination).await?;
+        materialized.push(destination);
+    }
+    Ok(materialized)
+}
+
+async fn sync_primary_runtime_skills(
+    fs: Arc<dyn ExecutorFileSystem>,
+    codex_home: &AbsolutePathBuf,
+    bundled_skill_paths: &[AbsolutePathBuf],
+    skills_to_remove: &[String],
+) -> Result<Vec<AbsolutePathBuf>, JSONRPCErrorError> {
+    if bundled_skill_paths.is_empty() && skills_to_remove.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    if bundled_skill_paths.is_empty() {
+        move_legacy_primary_runtime_skills(fs, codex_home, skills_to_remove).await?;
+        return Ok(Vec::new());
+    }
+
+    let destination_root = absolute_path(
+        codex_home
+            .as_path()
+            .join("skills")
+            .join(PUBLISHED_ARTIFACT_NAME),
+    )?;
+    let staging_root = temporary_sibling_path(&destination_root, "staging")?;
+    let result = async {
+        create_directory(Arc::clone(&fs), &staging_root).await?;
+
+        let mut materialized = Vec::with_capacity(bundled_skill_paths.len());
+        for bundled_skill_path in bundled_skill_paths {
+            let skill_root = absolute_path(
+                bundled_skill_path
+                    .as_path()
+                    .parent()
+                    .ok_or_else(|| {
+                        invalid_params(format!(
+                            "bundled skill path {} has no parent directory",
+                            bundled_skill_path.display()
+                        ))
+                    })?
+                    .to_path_buf(),
+            )?;
+            let skill_name = skill_root.as_path().file_name().ok_or_else(|| {
+                invalid_params(format!(
+                    "bundled skill path {} has no skill directory name",
+                    bundled_skill_path.display()
+                ))
+            })?;
+            let staged_skill_root = absolute_path(staging_root.as_path().join(skill_name))?;
+            copy_directory(Arc::clone(&fs), &skill_root, &staged_skill_root).await?;
+            materialized.push(absolute_path(
+                destination_root.as_path().join(skill_name).join("SKILL.md"),
+            )?);
+        }
+
+        publish_staged_directory(Arc::clone(&fs), &staging_root, &destination_root).await?;
+        move_legacy_primary_runtime_skills(Arc::clone(&fs), codex_home, skills_to_remove).await?;
+        Ok(materialized)
+    }
+    .await;
+    cleanup_directory(&fs, &staging_root, "staged primary runtime skills").await;
+    result
+}
+
+async fn move_legacy_primary_runtime_skills(
+    fs: Arc<dyn ExecutorFileSystem>,
+    codex_home: &AbsolutePathBuf,
+    skills_to_remove: &[String],
+) -> Result<(), JSONRPCErrorError> {
+    if skills_to_remove.is_empty() {
+        return Ok(());
+    }
+
+    let skills_root = absolute_path(codex_home.as_path().join("skills"))?;
+    for skill_dir in skills_to_remove {
+        let skill_root = resolve_legacy_skill_directory(&skills_root, skill_dir)?;
+        let metadata = match fs.get_metadata(&skill_root, /*sandbox*/ None).await {
+            Ok(metadata) => metadata,
+            Err(err) if err.kind() == io::ErrorKind::NotFound => continue,
+            Err(err) => {
+                return Err(internal_error(format!(
+                    "failed to inspect legacy skill directory {}: {err}",
+                    skill_root.display()
+                )));
+            }
+        };
+        if !metadata.is_directory {
+            continue;
+        }
+
+        let backup_path = absolute_path(
+            codex_home
+                .as_path()
+                .join(".tmp")
+                .join("legacy-primary-runtime-skills")
+                .join(format!(
+                    "{}-{}",
+                    skill_root
+                        .as_path()
+                        .file_name()
+                        .and_then(OsStr::to_str)
+                        .unwrap_or("skill"),
+                    Uuid::new_v4()
+                )),
+        )?;
+        if let Some(parent) = backup_path.as_path().parent() {
+            create_directory(Arc::clone(&fs), &absolute_path(parent.to_path_buf())?).await?;
+        }
+        copy_directory(Arc::clone(&fs), &skill_root, &backup_path).await?;
+        remove_if_exists(
+            Arc::clone(&fs),
+            &skill_root,
+            RemoveOptions {
+                recursive: true,
+                force: true,
+            },
+        )
+        .await?;
+        tracing::info!(
+            skill_dir = %skill_dir,
+            skill_root = %skill_root.display(),
+            backup_path = %backup_path.display(),
+            "moved legacy primary runtime skill"
+        );
+    }
+    Ok(())
+}
+
+fn resolve_legacy_skill_directory(
+    skills_root: &AbsolutePathBuf,
+    skill_dir: &str,
+) -> Result<AbsolutePathBuf, JSONRPCErrorError> {
+    let relative = Path::new(skill_dir);
+    if !relative
+        .components()
+        .all(|component| matches!(component, Component::Normal(_)))
+    {
+        return Err(invalid_params(format!(
+            "legacy primary runtime skill path must stay within the skills directory: {skill_dir}"
+        )));
+    }
+    absolute_path(skills_root.as_path().join(relative))
+}
+
+async fn replace_directory(
+    fs: Arc<dyn ExecutorFileSystem>,
+    source: &AbsolutePathBuf,
+    destination: &AbsolutePathBuf,
+) -> Result<(), JSONRPCErrorError> {
+    if let Some(parent) = destination.as_path().parent() {
+        create_directory(Arc::clone(&fs), &absolute_path(parent.to_path_buf())?).await?;
+    }
+    let staging_path = temporary_sibling_path(destination, "staging")?;
+    let result = async {
+        copy_directory(Arc::clone(&fs), source, &staging_path).await?;
+        publish_staged_directory(Arc::clone(&fs), &staging_path, destination).await
+    }
+    .await;
+    cleanup_directory(&fs, &staging_path, "staged runtime directory").await;
+    result
+}
+
+async fn publish_staged_directory(
+    fs: Arc<dyn ExecutorFileSystem>,
+    staging_path: &AbsolutePathBuf,
+    destination: &AbsolutePathBuf,
+) -> Result<(), JSONRPCErrorError> {
+    let backup_path = temporary_sibling_path(destination, "previous")?;
+    let result = async {
+        let destination_exists = path_exists(Arc::clone(&fs), destination).await?;
+        if destination_exists {
+            copy_directory(Arc::clone(&fs), destination, &backup_path).await?;
+        }
+
+        remove_if_exists(
+            Arc::clone(&fs),
+            destination,
+            RemoveOptions {
+                recursive: true,
+                force: true,
+            },
+        )
+        .await?;
+
+        if let Err(error) = copy_directory(Arc::clone(&fs), staging_path, destination).await {
+            remove_if_exists(
+                Arc::clone(&fs),
+                destination,
+                RemoveOptions {
+                    recursive: true,
+                    force: true,
+                },
+            )
+            .await?;
+            if destination_exists
+                && let Err(restore_error) =
+                    copy_directory(Arc::clone(&fs), &backup_path, destination).await
+            {
+                return Err(internal_error(format!(
+                    "failed to restore published runtime directory {} after replacement failed: {}; restore failed: {}",
+                    destination.display(),
+                    error.message,
+                    restore_error.message
+                )));
+            }
+            return Err(error);
+        }
+
+        Ok(())
+    }
+    .await;
+    if result.is_ok() {
+        cleanup_directory(&fs, &backup_path, "previous runtime directory").await;
+    }
+    result
+}
+
+async fn copy_directory(
+    fs: Arc<dyn ExecutorFileSystem>,
+    source: &AbsolutePathBuf,
+    destination: &AbsolutePathBuf,
+) -> Result<(), JSONRPCErrorError> {
+    fs.copy(
+        source,
+        destination,
+        CopyOptions { recursive: true },
+        /*sandbox*/ None,
+    )
+    .await
+    .map_err(|err| {
+        internal_error(format!(
+            "failed to copy directory {} to {}: {err}",
+            source.display(),
+            destination.display()
+        ))
+    })
+}
+
+async fn create_directory(
+    fs: Arc<dyn ExecutorFileSystem>,
+    path: &AbsolutePathBuf,
+) -> Result<(), JSONRPCErrorError> {
+    fs.create_directory(
+        path,
+        CreateDirectoryOptions { recursive: true },
+        /*sandbox*/ None,
+    )
+    .await
+    .map_err(|err| {
+        internal_error(format!(
+            "failed to create directory {}: {err}",
+            path.display()
+        ))
+    })
+}
+
+async fn remove_if_exists(
+    fs: Arc<dyn ExecutorFileSystem>,
+    path: &AbsolutePathBuf,
+    options: RemoveOptions,
+) -> Result<(), JSONRPCErrorError> {
+    match fs.remove(path, options, /*sandbox*/ None).await {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(internal_error(format!(
+            "failed to remove directory {}: {err}",
+            path.display()
+        ))),
+    }
+}
+
+async fn path_exists(
+    fs: Arc<dyn ExecutorFileSystem>,
+    path: &AbsolutePathBuf,
+) -> Result<bool, JSONRPCErrorError> {
+    match fs.get_metadata(path, /*sandbox*/ None).await {
+        Ok(_) => Ok(true),
+        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(false),
+        Err(err) => Err(internal_error(format!(
+            "failed to inspect runtime path {}: {err}",
+            path.display()
+        ))),
+    }
+}
+
+async fn cleanup_directory(fs: &Arc<dyn ExecutorFileSystem>, path: &AbsolutePathBuf, label: &str) {
+    if let Err(error) = remove_if_exists(
+        Arc::clone(fs),
+        path,
+        RemoveOptions {
+            recursive: true,
+            force: true,
+        },
+    )
+    .await
+    {
+        tracing::warn!(
+            path = %path.display(),
+            error = %error.message,
+            "failed to clean up {label}"
+        );
+    }
+}
+
+fn temporary_sibling_path(
+    destination: &AbsolutePathBuf,
+    label: &str,
+) -> Result<AbsolutePathBuf, JSONRPCErrorError> {
+    let parent = destination.as_path().parent().ok_or_else(|| {
+        internal_error(format!(
+            "runtime destination {} has no parent directory",
+            destination.display()
+        ))
+    })?;
+    let destination_name = destination
+        .as_path()
+        .file_name()
+        .map(safe_path_segment)
+        .unwrap_or_else(|| "runtime-item".to_string());
+    absolute_path(parent.join(format!(".{destination_name}-{label}-{}", Uuid::new_v4())))
+}
+
+fn safe_path_segment(segment: &OsStr) -> String {
+    let safe = segment
+        .to_string_lossy()
+        .chars()
+        .map(|ch| {
+            if ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '.') {
+                ch
+            } else {
+                '-'
+            }
+        })
+        .collect::<String>();
+    let safe = safe.trim_matches('.').to_string();
+    if safe.is_empty() || safe == ".." {
+        "runtime-item".to_string()
+    } else {
+        safe
+    }
+}
+
+fn absolute_path(path: PathBuf) -> Result<AbsolutePathBuf, JSONRPCErrorError> {
+    AbsolutePathBuf::from_absolute_path_checked(path)
+        .map_err(|err| internal_error(format!("runtime path is not absolute: {err}")))
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use codex_app_server_protocol::RuntimeInstallPaths;
+    use codex_exec_server::LocalFileSystem;
+    use pretty_assertions::assert_eq;
+    use tokio::fs;
+
+    use super::*;
+
+    #[tokio::test]
+    async fn finalize_runtime_paths_materializes_marketplaces_and_skills() {
+        let codex_home = tempfile::tempdir().expect("codex home");
+        let runtime = tempfile::tempdir().expect("runtime");
+        let marketplace_root = runtime.path().join("market");
+        fs::create_dir_all(marketplace_root.join(".agents/plugins"))
+            .await
+            .expect("create marketplace manifest dir");
+        fs::write(
+            marketplace_root.join(".agents/plugins/marketplace.json"),
+            r#"{"name":"debug","plugins":[]}"#,
+        )
+        .await
+        .expect("write marketplace");
+
+        let bundled_skill_root = runtime.path().join("skills").join("debug");
+        fs::create_dir_all(&bundled_skill_root)
+            .await
+            .expect("create bundled skill");
+        fs::write(bundled_skill_root.join("SKILL.md"), "debug")
+            .await
+            .expect("write bundled skill");
+
+        let legacy_skill_root = codex_home.path().join("skills").join("legacy");
+        fs::create_dir_all(&legacy_skill_root)
+            .await
+            .expect("create legacy skill");
+        fs::write(legacy_skill_root.join("SKILL.md"), "legacy")
+            .await
+            .expect("write legacy skill");
+
+        let paths = RuntimeInstallPaths {
+            bundled_plugin_marketplace_paths: vec![
+                absolute_path(marketplace_root).expect("absolute marketplace path"),
+            ],
+            bundled_skill_paths: vec![
+                absolute_path(bundled_skill_root.join("SKILL.md")).expect("absolute skill path"),
+            ],
+            node_modules_path: absolute_path(runtime.path().join("node_modules"))
+                .expect("absolute node modules path"),
+            node_path: absolute_path(runtime.path().join("node")).expect("absolute node path"),
+            python_path: absolute_path(runtime.path().join("python"))
+                .expect("absolute python path"),
+            skills_to_remove: vec!["legacy".to_string()],
+        };
+
+        let finalized = finalize_runtime_paths(
+            Arc::new(LocalFileSystem::unsandboxed()),
+            &absolute_path(codex_home.path().to_path_buf()).expect("absolute codex home"),
+            paths,
+        )
+        .await
+        .expect("finalize runtime paths");
+
+        let expected_marketplace_root = codex_home
+            .path()
+            .join("plugins")
+            .join(PUBLISHED_ARTIFACT_NAME)
+            .join("marketplaces")
+            .join("market");
+        let expected_skill_path = codex_home
+            .path()
+            .join("skills")
+            .join(PUBLISHED_ARTIFACT_NAME)
+            .join("debug")
+            .join("SKILL.md");
+        assert_eq!(
+            finalized.bundled_plugin_marketplace_paths,
+            vec![absolute_path(expected_marketplace_root.clone()).expect("absolute path")]
+        );
+        assert_eq!(
+            finalized.bundled_skill_paths,
+            vec![absolute_path(expected_skill_path.clone()).expect("absolute path")]
+        );
+        assert!(
+            expected_marketplace_root
+                .join(".agents/plugins/marketplace.json")
+                .is_file()
+        );
+        assert_eq!(
+            fs::read_to_string(expected_skill_path)
+                .await
+                .expect("read materialized skill"),
+            "debug"
+        );
+        assert!(!legacy_skill_root.exists());
+        assert_eq!(
+            std::fs::read_dir(
+                codex_home
+                    .path()
+                    .join(".tmp")
+                    .join("legacy-primary-runtime-skills")
+            )
+            .expect("read legacy backups")
+            .count(),
+            1
+        );
+    }
+
+    #[tokio::test]
+    async fn move_legacy_primary_runtime_skills_rejects_parent_path_without_removing_skill() {
+        let codex_home = tempfile::tempdir().expect("codex home");
+        let existing_skill_path = codex_home
+            .path()
+            .join("skills")
+            .join("existing")
+            .join("SKILL.md");
+        fs::create_dir_all(existing_skill_path.parent().expect("skill parent"))
+            .await
+            .expect("create existing skill");
+        fs::write(&existing_skill_path, "existing")
+            .await
+            .expect("write existing skill");
+
+        let error = move_legacy_primary_runtime_skills(
+            Arc::new(LocalFileSystem::unsandboxed()),
+            &absolute_path(codex_home.path().to_path_buf()).expect("absolute codex home"),
+            &["../existing".to_string()],
+        )
+        .await
+        .expect_err("parent path should fail");
+
+        assert!(
+            error.message.contains(
+                "legacy primary runtime skill path must stay within the skills directory"
+            )
+        );
+        assert_eq!(
+            fs::read_to_string(existing_skill_path)
+                .await
+                .expect("read existing skill"),
+            "existing"
+        );
+    }
+
+    #[tokio::test]
+    async fn materialize_bundled_plugin_marketplaces_preserves_existing_copy_on_copy_failure() {
+        let codex_home = tempfile::tempdir().expect("codex home");
+        let runtime = tempfile::tempdir().expect("runtime");
+        let missing_marketplace_root = runtime.path().join("market");
+        let published_manifest = codex_home
+            .path()
+            .join("plugins")
+            .join(PUBLISHED_ARTIFACT_NAME)
+            .join("marketplaces")
+            .join("market")
+            .join(".agents/plugins/marketplace.json");
+        fs::create_dir_all(published_manifest.parent().expect("manifest parent"))
+            .await
+            .expect("create published marketplace");
+        fs::write(&published_manifest, "previous")
+            .await
+            .expect("write published marketplace");
+
+        let error = materialize_bundled_plugin_marketplaces(
+            Arc::new(LocalFileSystem::unsandboxed()),
+            &absolute_path(codex_home.path().to_path_buf()).expect("absolute codex home"),
+            &[absolute_path(missing_marketplace_root).expect("absolute marketplace path")],
+        )
+        .await
+        .expect_err("missing marketplace should fail");
+
+        assert!(error.message.contains("failed to copy directory"));
+        assert_eq!(
+            fs::read_to_string(published_manifest)
+                .await
+                .expect("read published marketplace"),
+            "previous"
+        );
+    }
+
+    #[tokio::test]
+    async fn sync_primary_runtime_skills_preserves_existing_copy_on_copy_failure() {
+        let codex_home = tempfile::tempdir().expect("codex home");
+        let runtime = tempfile::tempdir().expect("runtime");
+        let missing_skill_path = runtime.path().join("skills").join("debug").join("SKILL.md");
+        let published_skill_path = codex_home
+            .path()
+            .join("skills")
+            .join(PUBLISHED_ARTIFACT_NAME)
+            .join("existing")
+            .join("SKILL.md");
+        fs::create_dir_all(published_skill_path.parent().expect("skill parent"))
+            .await
+            .expect("create published skill");
+        fs::write(&published_skill_path, "previous")
+            .await
+            .expect("write published skill");
+
+        let error = sync_primary_runtime_skills(
+            Arc::new(LocalFileSystem::unsandboxed()),
+            &absolute_path(codex_home.path().to_path_buf()).expect("absolute codex home"),
+            &[absolute_path(missing_skill_path).expect("absolute skill path")],
+            &[],
+        )
+        .await
+        .expect_err("missing skill should fail");
+
+        assert!(error.message.contains("failed to copy directory"));
+        assert_eq!(
+            fs::read_to_string(published_skill_path)
+                .await
+                .expect("read published skill"),
+            "previous"
+        );
+    }
+}

codex-rs/exec-server/Cargo.toml

@@ -30,6 +30,8 @@ reqwest = { workspace = true, features = ["json", "rustls-tls", "stream"] }
 prost = "0.14.3"
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
+sha2 = { workspace = true }
+tempfile = { workspace = true }
 thiserror = { workspace = true }
 toml = { workspace = true }
 tokio = { workspace = true, features = [
@@ -47,6 +49,7 @@ tokio-util = { workspace = true, features = ["rt"] }
 tokio-tungstenite = { workspace = true }
 tracing = { workspace = true }
 uuid = { workspace = true, features = ["v4"] }
+zip = { workspace = true }
 
 [dev-dependencies]
 anyhow = { workspace = true }
@@ -55,6 +58,5 @@ ctor = { workspace = true }
 http = { workspace = true }
 pretty_assertions = { workspace = true }
 serial_test = { workspace = true }
-tempfile = { workspace = true }
 test-case = "3.3.1"
 wiremock = { workspace = true }

codex-rs/exec-server/src/client.rs

@@ -8,6 +8,9 @@ use std::time::Duration;
 
 use arc_swap::ArcSwap;
 use codex_app_server_protocol::JSONRPCNotification;
+use codex_app_server_protocol::RuntimeInstallParams;
+use codex_app_server_protocol::RuntimeInstallResponse;
+use codex_utils_absolute_path::AbsolutePathBuf;
 use futures::FutureExt;
 use futures::future::BoxFuture;
 use serde_json::Value;
@@ -69,6 +72,7 @@ use crate::protocol::INITIALIZED_METHOD;
 use crate::protocol::InitializeParams;
 use crate::protocol::InitializeResponse;
 use crate::protocol::ProcessOutputChunk;
+use crate::protocol::RUNTIME_INSTALL_METHOD;
 use crate::protocol::ReadParams;
 use crate::protocol::ReadResponse;
 use crate::protocol::TerminateParams;
@@ -175,6 +179,7 @@ struct Inner {
     http_body_streams_write_lock: Mutex<()>,
     http_body_stream_next_id: AtomicU64,
     session_id: std::sync::RwLock<Option<String>>,
+    codex_home: std::sync::RwLock<Option<AbsolutePathBuf>>,
     reader_task: tokio::task::JoinHandle<()>,
 }
 
@@ -341,6 +346,14 @@ impl ExecServerClient {
                     .unwrap_or_else(std::sync::PoisonError::into_inner);
                 *session_id = Some(response.session_id.clone());
             }
+            {
+                let mut codex_home = self
+                    .inner
+                    .codex_home
+                    .write()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner);
+                *codex_home = Some(response.codex_home.clone());
+            }
             self.notify_initialized().await?;
             Ok(response)
         })
@@ -432,6 +445,13 @@ impl ExecServerClient {
         self.call(FS_COPY_METHOD, &params).await
     }
 
+    pub async fn runtime_install(
+        &self,
+        params: RuntimeInstallParams,
+    ) -> Result<RuntimeInstallResponse, ExecServerError> {
+        self.call(RUNTIME_INSTALL_METHOD, &params).await
+    }
+
     pub(crate) async fn register_session(
         &self,
         process_id: &ProcessId,
@@ -463,6 +483,14 @@ impl ExecServerClient {
         self.inner.disconnected.get().is_some() || self.inner.client.is_disconnected()
     }
 
+    pub fn codex_home(&self) -> Option<AbsolutePathBuf> {
+        self.inner
+            .codex_home
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+    }
+
     pub(crate) async fn connect(
         connection: JsonRpcConnection,
         options: ExecServerClientConnectOptions,
@@ -510,6 +538,7 @@ impl ExecServerClient {
                 http_body_streams_write_lock: Mutex::new(()),
                 http_body_stream_next_id: AtomicU64::new(1),
                 session_id: std::sync::RwLock::new(None),
+                codex_home: std::sync::RwLock::new(None),
                 reader_task,
             }
         });
@@ -912,6 +941,7 @@ mod tests {
     use codex_app_server_protocol::JSONRPCMessage;
     use codex_app_server_protocol::JSONRPCNotification;
     use codex_app_server_protocol::JSONRPCResponse;
+    use codex_utils_absolute_path::AbsolutePathBuf;
     use futures::SinkExt;
     use futures::StreamExt;
     use pretty_assertions::assert_eq;
@@ -1047,6 +1077,10 @@ mod tests {
                 id: request.id,
                 result: serde_json::to_value(InitializeResponse {
                     session_id: session_id.to_string(),
+                    codex_home: AbsolutePathBuf::try_from(
+                        std::env::current_dir().expect("current dir"),
+                    )
+                    .expect("absolute current dir"),
                 })
                 .expect("initialize response should serialize"),
             }),
@@ -1082,7 +1116,7 @@ mod tests {
                 program: "sh".to_string(),
                 args: vec![
                     "-c".to_string(),
-                    "read _line; printf '%s\\n' '{\"id\":1,\"result\":{\"sessionId\":\"stdio-test\"}}'; read _line; sleep 60".to_string(),
+                    "read _line; printf '%s\\n' '{\"id\":1,\"result\":{\"sessionId\":\"stdio-test\",\"codexHome\":\"/tmp\"}}'; read _line; sleep 60".to_string(),
                 ],
                 env: HashMap::new(),
                 cwd: None,
@@ -1106,7 +1140,7 @@ mod tests {
                     program: "sh".to_string(),
                     args: vec![
                         "-c".to_string(),
-                        "read _line; printf '%s\\n' '{\"id\":1,\"result\":{\"sessionId\":\"stdio-test\"}}'; read _line; sleep 60".to_string(),
+                        "read _line; printf '%s\\n' '{\"id\":1,\"result\":{\"sessionId\":\"stdio-test\",\"codexHome\":\"/tmp\"}}'; read _line; sleep 60".to_string(),
                     ],
                     env: HashMap::new(),
                     cwd: None,
@@ -1129,7 +1163,7 @@ mod tests {
                 args: vec![
                     "-NoProfile".to_string(),
                     "-Command".to_string(),
-                    "$null = [Console]::In.ReadLine(); [Console]::Out.WriteLine('{\"id\":1,\"result\":{\"sessionId\":\"stdio-test\"}}'); $null = [Console]::In.ReadLine(); Start-Sleep -Seconds 60".to_string(),
+                    "$null = [Console]::In.ReadLine(); [Console]::Out.WriteLine('{\"id\":1,\"result\":{\"sessionId\":\"stdio-test\",\"codexHome\":\"C:\\\\Users\\\\codex\\\\.codex\"}}'); $null = [Console]::In.ReadLine(); Start-Sleep -Seconds 60".to_string(),
                 ],
                 env: HashMap::new(),
                 cwd: None,
@@ -1154,7 +1188,7 @@ mod tests {
             "read _line; \
              echo \"$$\" > {}; \
              sleep 60 >/dev/null 2>&1 & echo \"$!\" > {}; \
-             printf '%s\\n' '{{\"id\":1,\"result\":{{\"sessionId\":\"stdio-test\"}}}}'; \
+             printf '%s\\n' '{{\"id\":1,\"result\":{{\"sessionId\":\"stdio-test\",\"codexHome\":\"/tmp\"}}}}'; \
              read _line; \
              wait",
             shell_quote(pid_file.as_path()),
@@ -1280,6 +1314,10 @@ mod tests {
                     id: request.id,
                     result: serde_json::to_value(InitializeResponse {
                         session_id: "session-1".to_string(),
+                        codex_home: AbsolutePathBuf::try_from(
+                            std::env::current_dir().expect("current dir"),
+                        )
+                        .expect("absolute current dir"),
                     })
                     .expect("initialize response should serialize"),
                 }),
@@ -1423,6 +1461,10 @@ mod tests {
                     id: request.id,
                     result: serde_json::to_value(InitializeResponse {
                         session_id: "session-1".to_string(),
+                        codex_home: AbsolutePathBuf::try_from(
+                            std::env::current_dir().expect("current dir"),
+                        )
+                        .expect("absolute current dir"),
                     })
                     .expect("initialize response should serialize"),
                 }),
@@ -1560,6 +1602,10 @@ mod tests {
                     id: request.id,
                     result: serde_json::to_value(InitializeResponse {
                         session_id: "session-1".to_string(),
+                        codex_home: AbsolutePathBuf::try_from(
+                            std::env::current_dir().expect("current dir"),
+                        )
+                        .expect("absolute current dir"),
                     })
                     .expect("initialize response should serialize"),
                 }),

codex-rs/exec-server/src/codex_home.rs

@@ -0,0 +1,26 @@
+use std::path::PathBuf;
+
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use crate::rpc::internal_error;
+
+pub(crate) fn default_codex_home() -> Result<AbsolutePathBuf, JSONRPCErrorError> {
+    default_codex_home_path()
+        .and_then(|path| {
+            AbsolutePathBuf::from_absolute_path_checked(path)
+                .map_err(|err| format!("runtime codex home is not absolute: {err}"))
+        })
+        .map_err(internal_error)
+}
+
+pub(crate) fn default_codex_home_path() -> Result<PathBuf, String> {
+    if let Some(codex_home) = std::env::var_os("CODEX_HOME") {
+        return Ok(PathBuf::from(codex_home));
+    }
+    let home = std::env::var_os("HOME")
+        .or_else(|| std::env::var_os("USERPROFILE"))
+        .map(PathBuf::from)
+        .ok_or_else(|| "failed to locate home directory".to_string())?;
+    Ok(home.join(".codex"))
+}

codex-rs/exec-server/src/environment.rs

@@ -2,6 +2,12 @@ use std::collections::HashMap;
 use std::sync::Arc;
 use std::sync::RwLock;
 
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::RuntimeInstallParams;
+use codex_app_server_protocol::RuntimeInstallResponse;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use tokio_util::sync::CancellationToken;
+
 use crate::ExecServerError;
 use crate::ExecServerRuntimePaths;
 use crate::ExecutorFileSystem;
@@ -9,6 +15,7 @@ use crate::HttpClient;
 use crate::client::LazyRemoteExecServerClient;
 use crate::client::http_client::ReqwestHttpClient;
 use crate::client_api::ExecServerTransportParams;
+use crate::codex_home::default_codex_home_path;
 use crate::environment_provider::DefaultEnvironmentProvider;
 use crate::environment_provider::EnvironmentDefault;
 use crate::environment_provider::EnvironmentProvider;
@@ -20,6 +27,7 @@ use crate::local_process::LocalProcess;
 use crate::process::ExecBackend;
 use crate::remote_file_system::RemoteFileSystem;
 use crate::remote_process::RemoteProcess;
+use crate::rpc::internal_error;
 
 pub const CODEX_EXEC_SERVER_URL_ENV_VAR: &str = "CODEX_EXEC_SERVER_URL";
 
@@ -91,7 +99,13 @@ impl EnvironmentManager {
         local_runtime_paths: Option<ExecServerRuntimePaths>,
     ) -> Result<Self, ExecServerError> {
         let provider = environment_provider_from_codex_home(codex_home.as_ref())?;
-        Self::from_snapshot(provider.snapshot().await?, local_runtime_paths)
+        let local_codex_home = AbsolutePathBuf::from_absolute_path_checked(codex_home.as_ref())
+            .map_err(|err| ExecServerError::Protocol(err.to_string()))?;
+        Self::from_snapshot_with_codex_home(
+            provider.snapshot().await?,
+            local_runtime_paths,
+            Some(local_codex_home),
+        )
     }
 
     /// Builds a manager from the legacy environment-variable provider without
@@ -131,6 +145,18 @@ impl EnvironmentManager {
     fn from_snapshot(
         snapshot: EnvironmentProviderSnapshot,
         local_runtime_paths: Option<ExecServerRuntimePaths>,
+    ) -> Result<Self, ExecServerError> {
+        Self::from_snapshot_with_codex_home(
+            snapshot,
+            local_runtime_paths,
+            default_local_codex_home(),
+        )
+    }
+
+    fn from_snapshot_with_codex_home(
+        snapshot: EnvironmentProviderSnapshot,
+        local_runtime_paths: Option<ExecServerRuntimePaths>,
+        local_codex_home: Option<AbsolutePathBuf>,
     ) -> Result<Self, ExecServerError> {
         let EnvironmentProviderSnapshot {
             environments,
@@ -145,7 +171,10 @@ impl EnvironmentManager {
                     "local environment requires configured runtime paths".to_string(),
                 )
             })?;
-            let local_environment = Arc::new(Environment::local(local_runtime_paths));
+            let local_environment = Arc::new(Environment::local_with_codex_home(
+                local_runtime_paths,
+                local_codex_home,
+            ));
             environment_map.insert(
                 LOCAL_ENVIRONMENT_ID.to_string(),
                 Arc::clone(&local_environment),
@@ -289,7 +318,66 @@ pub struct Environment {
     exec_backend: Arc<dyn ExecBackend>,
     filesystem: Arc<dyn ExecutorFileSystem>,
     http_client: Arc<dyn HttpClient>,
+    runtime_installer: RuntimeInstaller,
     local_runtime_paths: Option<ExecServerRuntimePaths>,
+    codex_home: Option<AbsolutePathBuf>,
+}
+
+#[derive(Clone)]
+enum RuntimeInstaller {
+    Local,
+    Remote(LazyRemoteExecServerClient),
+}
+
+impl RuntimeInstaller {
+    async fn install_runtime(
+        &self,
+        params: RuntimeInstallParams,
+    ) -> Result<RuntimeInstallResponse, JSONRPCErrorError> {
+        self.install_runtime_with_progress(params, /*progress*/ None, CancellationToken::new())
+            .await
+    }
+
+    async fn install_runtime_with_progress(
+        &self,
+        params: RuntimeInstallParams,
+        progress: Option<crate::runtime_install::RuntimeInstallProgressSender>,
+        cancellation: CancellationToken,
+    ) -> Result<RuntimeInstallResponse, JSONRPCErrorError> {
+        match self {
+            RuntimeInstaller::Local => match progress {
+                Some(progress) => {
+                    crate::runtime_install::install_runtime_with_progress(
+                        params,
+                        progress,
+                        cancellation,
+                    )
+                    .await
+                }
+                None => crate::runtime_install::install_runtime(params).await,
+            },
+            RuntimeInstaller::Remote(client) => {
+                let client = client.get().await.map_err(exec_server_error_to_jsonrpc)?;
+                tokio::select! {
+                    _ = cancellation.cancelled() => Err(internal_error("runtime install canceled")),
+                    response = client.runtime_install(params) => {
+                        response.map_err(exec_server_error_to_jsonrpc)
+                    }
+                }
+            }
+        }
+    }
+}
+
+fn exec_server_error_to_jsonrpc(err: ExecServerError) -> JSONRPCErrorError {
+    match err {
+        ExecServerError::Server { code, message } => JSONRPCErrorError {
+            code,
+            data: None,
+            message,
+        },
+        _ => internal_error(err.to_string()),
+    }
 }
 
 impl Environment {
@@ -301,7 +389,9 @@ impl Environment {
             exec_backend: Arc::new(LocalProcess::default()),
             filesystem: Arc::new(LocalFileSystem::unsandboxed()),
             http_client: Arc::new(ReqwestHttpClient),
+            runtime_installer: RuntimeInstaller::Local,
             local_runtime_paths: None,
+            codex_home: default_local_codex_home(),
         }
     }
 }
@@ -351,6 +441,13 @@ impl Environment {
     }
 
     pub(crate) fn local(local_runtime_paths: ExecServerRuntimePaths) -> Self {
+        Self::local_with_codex_home(local_runtime_paths, default_local_codex_home())
+    }
+
+    fn local_with_codex_home(
+        local_runtime_paths: ExecServerRuntimePaths,
+        codex_home: Option<AbsolutePathBuf>,
+    ) -> Self {
         Self {
             exec_server_url: None,
             remote_transport: None,
@@ -359,7 +456,9 @@ impl Environment {
                 local_runtime_paths.clone(),
             )),
             http_client: Arc::new(ReqwestHttpClient),
+            runtime_installer: RuntimeInstaller::Local,
             local_runtime_paths: Some(local_runtime_paths),
+            codex_home,
         }
     }
 
@@ -388,14 +487,17 @@ impl Environment {
         let exec_backend: Arc<dyn ExecBackend> = Arc::new(RemoteProcess::new(client.clone()));
         let filesystem: Arc<dyn ExecutorFileSystem> =
             Arc::new(RemoteFileSystem::new(client.clone()));
+        let http_client = client.clone();
 
         Self {
             exec_server_url,
             remote_transport: Some(remote_transport),
             exec_backend,
             filesystem,
-            http_client: Arc::new(client),
+            http_client: Arc::new(http_client),
+            runtime_installer: RuntimeInstaller::Remote(client),
             local_runtime_paths,
+            codex_home: None,
         }
     }
 
@@ -423,6 +525,47 @@ impl Environment {
     pub fn get_filesystem(&self) -> Arc<dyn ExecutorFileSystem> {
         Arc::clone(&self.filesystem)
     }
+
+    pub async fn install_runtime(
+        &self,
+        params: RuntimeInstallParams,
+    ) -> Result<RuntimeInstallResponse, JSONRPCErrorError> {
+        self.runtime_installer.install_runtime(params).await
+    }
+
+    pub async fn install_runtime_with_progress(
+        &self,
+        params: RuntimeInstallParams,
+        progress: crate::runtime_install::RuntimeInstallProgressSender,
+        cancellation: CancellationToken,
+    ) -> Result<RuntimeInstallResponse, JSONRPCErrorError> {
+        self.runtime_installer
+            .install_runtime_with_progress(params, Some(progress), cancellation)
+            .await
+    }
+
+    pub async fn codex_home(&self) -> Result<AbsolutePathBuf, JSONRPCErrorError> {
+        if let Some(codex_home) = self.codex_home.clone() {
+            return Ok(codex_home);
+        }
+        match &self.runtime_installer {
+            RuntimeInstaller::Local => default_local_codex_home().ok_or_else(|| {
+                internal_error("failed to locate local codex home for runtime install")
+            }),
+            RuntimeInstaller::Remote(client) => {
+                let client = client.get().await.map_err(exec_server_error_to_jsonrpc)?;
+                client
+                    .codex_home()
+                    .ok_or_else(|| internal_error("remote exec-server did not report a codex home"))
+            }
+        }
+    }
+}
+
+fn default_local_codex_home() -> Option<AbsolutePathBuf> {
+    default_codex_home_path()
+        .ok()
+        .and_then(|path| AbsolutePathBuf::from_absolute_path_checked(path).ok())
 }
 
 #[cfg(test)]

codex-rs/exec-server/src/lib.rs

@@ -1,6 +1,7 @@
 mod client;
 mod client_api;
 mod client_transport;
+mod codex_home;
 mod connection;
 mod environment;
 mod environment_provider;
@@ -19,6 +20,7 @@ mod remote;
 mod remote_file_system;
 mod remote_process;
 mod rpc;
+mod runtime_install;
 mod runtime_paths;
 mod sandboxed_file_system;
 mod server;
@@ -84,6 +86,7 @@ pub use protocol::HttpRequestResponse;
 pub use protocol::InitializeParams;
 pub use protocol::InitializeResponse;
 pub use protocol::ProcessOutputChunk;
+pub use protocol::RUNTIME_INSTALL_METHOD;
 pub use protocol::ReadParams;
 pub use protocol::ReadResponse;
 pub use protocol::TerminateParams;

codex-rs/exec-server/src/protocol.rs

@@ -30,6 +30,7 @@ pub const FS_COPY_METHOD: &str = "fs/copy";
 pub const HTTP_REQUEST_METHOD: &str = "http/request";
 /// JSON-RPC notification method for streamed executor HTTP response bodies.
 pub const HTTP_REQUEST_BODY_DELTA_METHOD: &str = "http/request/bodyDelta";
+pub const RUNTIME_INSTALL_METHOD: &str = "runtime/install";
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(transparent)]
@@ -59,6 +60,7 @@ pub struct InitializeParams {
 #[serde(rename_all = "camelCase")]
 pub struct InitializeResponse {
     pub session_id: String,
+    pub codex_home: AbsolutePathBuf,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]

codex-rs/exec-server/src/rpc.rs

@@ -80,7 +80,7 @@ impl RpcNotificationSender {
         self.outgoing_tx
             .send(RpcServerOutboundMessage::Response { request_id, result })
             .await
-            .map_err(|_| internal_error("RPC connection closed while sending response".into()))
+            .map_err(|_| internal_error("RPC connection closed while sending response"))
     }
 
     pub(crate) async fn notify<P: Serialize>(
@@ -97,7 +97,7 @@ impl RpcNotificationSender {
                 },
             ))
             .await
-            .map_err(|_| internal_error("RPC connection closed while sending notification".into()))
+            .map_err(|_| internal_error("RPC connection closed while sending notification"))
     }
 }
 
@@ -425,11 +425,11 @@ pub(crate) fn method_not_found(message: String) -> JSONRPCErrorError {
     }
 }
 
-pub(crate) fn invalid_params(message: String) -> JSONRPCErrorError {
+pub(crate) fn invalid_params(message: impl Into<String>) -> JSONRPCErrorError {
     JSONRPCErrorError {
         code: -32602,
         data: None,
-        message,
+        message: message.into(),
     }
 }
 
@@ -441,11 +441,11 @@ pub(crate) fn not_found(message: String) -> JSONRPCErrorError {
     }
 }
 
-pub(crate) fn internal_error(message: String) -> JSONRPCErrorError {
+pub(crate) fn internal_error(message: impl Into<String>) -> JSONRPCErrorError {
     JSONRPCErrorError {
         code: -32603,
         data: None,
-        message,
+        message: message.into(),
     }
 }
 

codex-rs/exec-server/src/server/handler.rs

@@ -5,6 +5,8 @@ use std::sync::atomic::Ordering;
 
 use codex_app_server_protocol::JSONRPCErrorError;
 use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::RuntimeInstallParams;
+use codex_app_server_protocol::RuntimeInstallResponse;
 use serde_json::to_value;
 use std::collections::HashSet;
 use tokio::sync::Mutex;
@@ -123,7 +125,10 @@ impl ExecServerHandler {
             .session
             .lock()
             .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(session);
-        Ok(InitializeResponse { session_id })
+        Ok(InitializeResponse {
+            session_id,
+            codex_home: crate::codex_home::default_codex_home()?,
+        })
     }
 
     pub(crate) fn initialized(&self) -> Result<(), String> {
@@ -264,6 +269,14 @@ impl ExecServerHandler {
         self.file_system.copy(params).await
     }
 
+    pub(crate) async fn runtime_install(
+        &self,
+        params: RuntimeInstallParams,
+    ) -> Result<RuntimeInstallResponse, JSONRPCErrorError> {
+        self.require_initialized_for("runtime")?;
+        crate::runtime_install::install_runtime(params).await
+    }
+
     fn require_initialized_for(
         &self,
         method_family: &str,

codex-rs/exec-server/src/server/registry.rs

@@ -24,11 +24,13 @@ use crate::protocol::HttpRequestParams;
 use crate::protocol::INITIALIZE_METHOD;
 use crate::protocol::INITIALIZED_METHOD;
 use crate::protocol::InitializeParams;
+use crate::protocol::RUNTIME_INSTALL_METHOD;
 use crate::protocol::ReadParams;
 use crate::protocol::TerminateParams;
 use crate::protocol::WriteParams;
 use crate::rpc::RpcRouter;
 use crate::server::ExecServerHandler;
+use codex_app_server_protocol::RuntimeInstallParams;
 
 pub(crate) fn build_router() -> RpcRouter<ExecServerHandler> {
     let mut router = RpcRouter::new();
@@ -114,5 +116,11 @@ pub(crate) fn build_router() -> RpcRouter<ExecServerHandler> {
             handler.fs_copy(params).await
         },
     );
+    router.request(
+        RUNTIME_INSTALL_METHOD,
+        |handler: Arc<ExecServerHandler>, params: RuntimeInstallParams| async move {
+            handler.runtime_install(params).await
+        },
+    );
     router
 }

codex-rs/exec-server/tests/http_client.rs

@@ -17,6 +17,7 @@ use codex_exec_server::HttpRequestResponse;
 use codex_exec_server::InitializeParams;
 use codex_exec_server::InitializeResponse;
 use codex_exec_server::RemoteExecServerConnectArgs;
+use codex_utils_absolute_path::AbsolutePathBuf;
 use futures::SinkExt;
 use futures::StreamExt;
 use pretty_assertions::assert_eq;
@@ -1013,6 +1014,7 @@ impl JsonRpcPeer {
             request.id,
             InitializeResponse {
                 session_id: "session-1".to_string(),
+                codex_home: AbsolutePathBuf::try_from(std::env::current_dir()?)?,
             },
         )
         .await?;

codex-rs/tui/src/app/app_server_event_targets.rs

@@ -162,6 +162,7 @@ pub(super) fn server_notification_thread_target(
         | ServerNotification::FsChanged(_)
         | ServerNotification::WindowsWorldWritableWarning(_)
         | ServerNotification::WindowsSandboxSetupCompleted(_)
+        | ServerNotification::RuntimeInstallProgress(_)
         | ServerNotification::AccountLoginCompleted(_) => None,
     };
 
@@ -181,6 +182,8 @@ mod tests {
     use crate::test_support::PathBufExt;
     use crate::test_support::test_path_buf;
     use codex_app_server_protocol::GuardianWarningNotification;
+    use codex_app_server_protocol::RuntimeInstallProgressNotification;
+    use codex_app_server_protocol::RuntimeInstallProgressPhase;
     use codex_app_server_protocol::ServerNotification;
     use codex_app_server_protocol::ThreadSettings;
     use codex_app_server_protocol::ThreadSettingsUpdatedNotification;
@@ -230,6 +233,21 @@ mod tests {
         assert_eq!(target, ServerNotificationThreadTarget::Global);
     }
 
+    #[test]
+    fn runtime_install_progress_notifications_are_global() {
+        let notification =
+            ServerNotification::RuntimeInstallProgress(RuntimeInstallProgressNotification {
+                bundle_version: Some("v1".to_string()),
+                downloaded_bytes: None,
+                phase: RuntimeInstallProgressPhase::Checking,
+                total_bytes: None,
+            });
+
+        let target = server_notification_thread_target(&notification);
+
+        assert_eq!(target, ServerNotificationThreadTarget::Global);
+    }
+
     #[test]
     fn warning_notifications_route_to_threads_when_thread_id_is_present() {
         let thread_id = ThreadId::new();

codex-rs/tui/src/chatwidget/protocol.rs

@@ -239,6 +239,7 @@ impl ChatWidget {
             | ServerNotification::ThreadRealtimeTranscriptDone(_)
             | ServerNotification::WindowsWorldWritableWarning(_)
             | ServerNotification::WindowsSandboxSetupCompleted(_)
+            | ServerNotification::RuntimeInstallProgress(_)
             | ServerNotification::AccountLoginCompleted(_) => {}
             ServerNotification::ContextCompacted(_) => {}
         }