FEAT: Allowing Reinitialize in GUI for admins (#2833)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: richlundeen

.pyrit_conf_example

@@ -111,6 +111,15 @@ operation: op_trash_panda
 # Applies only to the pyrit_backend server.
 max_concurrent_scenario_runs: 3
 
+# Live Reinitialization
+# ---------------------
+# Allows administrators to apply saved configuration changes without restarting
+# the backend. Enable only when the deployment has exactly one backend process
+# and one replica. Known worker and replica settings are checked as an additional
+# safeguard. Live apply rejects busy runtimes and requires a restart if
+# initialization fails after replacement begins.
+enable_live_reinitialization: false
+
 # Custom Initializer Registration (REST API)
 # -------------------------------------------
 # When true, the REST API accepts POST /api/initializers to register custom

doc/code/setup/0_setup.md

@@ -27,3 +27,31 @@ PyRIT offers flexible configuration through:
 - **Custom initializers** for project-specific defaults
 
 See the detailed sections below for comprehensive setup guidance.
+
+## Reinitializing a running backend
+
+The CoPyRIT configuration page separates **Save** from **Reinitialize PyRIT**.
+On a single-process, single-replica backend, administrators can apply saved
+configuration, environment documents, and custom initializer scripts without
+restarting Python. The saved `.pyrit_conf` must set `enable_live_reinitialization: true`.
+See [the GUI reinitialization guide](../../gui/0_gui.md) for status, failure behavior, and deployment limits.
+
+The backend first validates the saved sources without changing live setup state. It rejects live apply while any
+runtime work is active. When the runtime is idle, it closes admission, checks for work again, and then rebuilds
+setup-owned registries and defaults. The replacement reuses the same memory object, which preserves in-memory and
+persisted history.
+Memory type, connection, or storage changes require a process restart.
+Library callers must provide their own admission and idle-runtime boundary
+before using this configuration-level reinitialization path.
+
+Reinitialization explicitly replaces process environment values supplied by the
+selected sources, including deployment-provided values. Omitted variables remain;
+there is no historical tracking or removal. Key Vault selection and `.env.local`
+priority still apply, and interpolation uses newly selected values. Ordinary
+initialization retains its existing environment precedence. The lower-level
+`initialize_pyrit_async(reinitialize=True)` option provides replacement values and
+memory reuse; `ConfigurationLoader` owns the complete registry/script rebuild.
+
+Failure after mutation blocks backend runtime operations until a process restart.
+Configuration repair stays available under the original authorization policy.
+Initializer side effects and environment updates are not rolled back.

doc/gui/0_gui.md

@@ -358,7 +358,55 @@ The **Configuration** page provides administrator-only editing for the files and
 - **Initializers** shows the read-only startup sequence from the active `.pyrit_conf`, in run order, along with the catalog of registered initializers.
 - **Custom Initializers** registers or removes Python initializer scripts. This tab requires `allow_custom_initializers: true`; scripts are stored in the configured local directory or Azure Blob container and must define a concrete `PyRITInitializer` subclass.
 
-Use **Reload** to discard local edits and fetch the latest source content. Saved configuration and environment changes take effect after restarting PyRIT. Custom initializer scripts execute under the backend service identity, so only trusted administrators should manage them.
+Use **Reload file** to fetch the latest source content; unsaved edits require explicit discard confirmation.
+**Save** only persists a source. **Reinitialize PyRIT** separately applies saved configuration, environment sources,
+and stored initializer scripts for every user of this backend. Save or discard editor changes first.
+Custom initializer scripts execute under the backend service identity, so only trusted administrators should manage them.
+
+### Reinitializing without a process restart
+
+Set `enable_live_reinitialization: true` in the saved `.pyrit_conf` to enable this administrator action. This setting
+is an explicit operator acknowledgement that the deployment has **one backend process and one replica**.
+It is disabled when `WEB_CONCURRENCY`, `UVICORN_WORKERS`, `PYRIT_API_WORKERS`, or `PYRIT_REPLICAS` specifies anything
+other than `1`. Do not use it behind a multi-worker server or across multiple replicas; it is not a distributed
+configuration update. External scaling settings cannot be discovered from within a process.
+
+Before replacement, PyRIT validates the saved configuration, environment sources, scripts, initializer parameters,
+and required environment values. Custom initializer scripts are trusted code. Importing a script or constructing its
+initializer can have side effects during validation.
+
+Reinitialization resets setup-owned component registries and recreates backend services. Components created only
+through the GUI must be recreated. The same memory object and persisted history are retained, including an in-memory
+database. Changing the memory type, Azure SQL connection, or Azure results storage configuration requires a backend
+restart and is rejected before replacement.
+
+Live apply does not stop or drain work. It rejects the request if a scenario, preparation, send, estimate, or other
+runtime operation is active. Wait for the work to finish, or cancel it with its existing control, and then retry.
+When the runtime is idle, PyRIT closes admission and checks again before it changes runtime state. This second check
+prevents newly admitted work from overlapping replacement.
+
+Operation status survives a browser disconnect or navigation; other connected clients detect runtime generation
+changes and refresh catalogs without discarding chat or configuration drafts.
+
+If validation fails, PyRIT does not change the live runtime. Repair the saved source and retry. If startup fails, or
+if live initialization fails after replacement starts, runtime operations stay unavailable until you restart the
+backend. The administration UI stays available for configuration repair. Authentication and authorization retain
+their process-start settings; reinitialization does not recreate them.
+
+Selected environment assignments replace existing process values, **including deployment-provided values**.
+Omitted variables remain unchanged; empty assignments set an empty value. Key Vault source selection and
+`.env.local` priority are preserved, and interpolation uses the new selected values. Ordinary library initialization
+keeps its existing precedence; replacement is an explicit reinitialization option. There is no rollback of
+environment assignments, initializer side effects, memory writes, or external actions if initialization fails.
+Listener and authentication settings remain process-start-only. This does not run a process supervisor, restart a
+container, or make local source files durable when a container is replaced.
+
+API clients can use administrator-only `GET /api/config/runtime`, `POST /api/config/runtime/apply`
+(`version`). Obtain the configuration version and opt-in state from `GET /api/config`. A newly admitted operation
+returns HTTP 202 and is tracked in status. Outcomes distinguish busy, unsupported, version-conflict,
+invalid-configuration, and restart-required. Authenticated non-admin clients can read readiness and generation only
+at `GET /api/runtime`.
+`GET /api/health` reports server responsiveness, not runtime readiness.
 
 ---
 

frontend/e2e/_runtime.ts

@@ -0,0 +1,17 @@
+import type { RuntimeReadiness, RuntimeStatus } from '../src/types'
+
+export const READY_RUNTIME: RuntimeReadiness = {
+  ready: true,
+  state: 'ready',
+  generation: 'e2e-runtime',
+}
+
+export const READY_RUNTIME_STATUS: RuntimeStatus = {
+  state: 'ready',
+  generation: READY_RUNTIME.generation,
+  version: 'e2e-config',
+  enabled: true,
+  applying: false,
+  outcome: 'success',
+  message: 'PyRIT is ready.',
+}

frontend/e2e/numeric-controls.spec.ts

@@ -2,6 +2,7 @@ import { expect, test, type Locator, type Page } from '@playwright/test'
 
 import type { RegisteredScenario } from '../src/types'
 
+import { READY_RUNTIME } from './_runtime'
 import { makeTarget } from './_targets'
 
 const SCENARIO: RegisteredScenario = {
@@ -40,6 +41,7 @@ async function mockNumericControlApis(page: Page): Promise<void> {
       '/api/auth/config': { clientId: '', tenantId: '', allowedGroupIds: '' },
       '/api/auth/access': { isAdmin: true },
       '/api/health': { status: 'healthy' },
+      '/api/runtime': READY_RUNTIME,
       '/api/version': { version: '1.2.0', display: 'Mock PyRIT', default_labels: { operator: 'test' } },
       '/api/targets': {
         items: [makeTarget({ target_registry_name: 'mock-target' })],

frontend/e2e/themes.spec.ts

@@ -1,6 +1,8 @@
 import { expect, test } from '@playwright/test'
 import type { Page, Route, TestInfo } from '@playwright/test'
 
+import { READY_RUNTIME, READY_RUNTIME_STATUS } from './_runtime'
+
 interface PresetCase {
   readonly id: string
   readonly label: string
@@ -29,6 +31,7 @@ const API_RESPONSES: Record<string, unknown> = {
   '/api/auth/config': { clientId: '', tenantId: '', allowedGroupIds: '' },
   '/api/auth/access': { isAdmin: true },
   '/api/health': { status: 'healthy' },
+  '/api/runtime': READY_RUNTIME,
   '/api/version': { version: 'theme-preview', display: 'theme-preview' },
   '/api/targets': EMPTY_PAGE,
   '/api/targets/catalog': { items: [] },
@@ -47,6 +50,7 @@ const API_RESPONSES: Record<string, unknown> = {
     queued: [],
   },
   '/api/config': { content: 'initializers: []\n', source: 'theme-preview', version: '1' },
+  '/api/config/runtime': READY_RUNTIME_STATUS,
   '/api/config/env-files': { items: [] },
   '/api/initializers': EMPTY_PAGE,
   '/api/initializers/custom': { items: [] },

frontend/e2e/touch-targets.spec.ts

@@ -1,5 +1,6 @@
 import { expect, test, type Locator, type Page } from "@playwright/test";
 import { makeAddMessageResponse } from "./_attacks";
+import { READY_RUNTIME, READY_RUNTIME_STATUS } from "./_runtime";
 import { makeTarget } from "./_targets";
 
 const MOBILE_VIEWPORT = { width: 390, height: 844 };
@@ -143,6 +144,10 @@ async function installTouchTargetMocks(page: Page): Promise<void> {
       await route.fulfill(jsonResponse({ isAdmin: true }));
       return;
     }
+    if (apiPath === "/runtime") {
+      await route.fulfill(jsonResponse(READY_RUNTIME));
+      return;
+    }
     if (apiPath === "/version") {
       await route.fulfill(
         jsonResponse({
@@ -179,6 +184,10 @@ async function installTouchTargetMocks(page: Page): Promise<void> {
       );
       return;
     }
+    if (apiPath === "/config/runtime" && method === "GET") {
+      await route.fulfill(jsonResponse(READY_RUNTIME_STATUS));
+      return;
+    }
     if (apiPath === "/initializers/settings" && method === "GET") {
       await route.fulfill(
         jsonResponse({

frontend/src/App.labels.test.tsx

@@ -35,6 +35,9 @@ jest.mock('@/utils/conversationExport', () => ({
 }))
 
 jest.mock('@/services/api', () => ({
+  runtimeApi: {
+    getReadiness: jest.fn().mockResolvedValue({ ready: true, state: 'ready', generation: '' }),
+  },
   authApi: { getAccess: jest.fn().mockResolvedValue({ isAdmin: false }) },
   versionApi: { getVersion: jest.fn() },
   labelsApi: { getLabels: jest.fn() },

frontend/src/App.targets.test.tsx

@@ -39,6 +39,9 @@ jest.mock('@/components/Layout/MainLayout', () => {
   }
 })
 jest.mock('@/services/api', () => ({
+  runtimeApi: {
+    getReadiness: jest.fn().mockResolvedValue({ ready: true, state: 'ready', generation: '' }),
+  },
   attacksApi: {
     getAttack: jest.fn(),
     getMessages: jest.fn(),

frontend/src/App.test.tsx

@@ -70,6 +70,9 @@ jest.mock("@azure/msal-react", () => ({
 }));
 
 jest.mock("./services/api", () => ({
+  runtimeApi: {
+    getReadiness: jest.fn().mockResolvedValue({ ready: true, state: 'ready', generation: '' }),
+  },
   attacksApi: {
     getAttack: jest.fn(),
     listAttacks: jest.fn(),