feat(settings): expose the agent execution mode (CodeAct) in the Settings UI (#4765)

Author: georgi

packages/agents/CLAUDE.md

@@ -482,8 +482,12 @@ Design and the research it follows (CodeAct, ICML 2024): docs/codeact-design.md.
 - The mode threads through `TaskExecutor`, `ParallelTaskExecutor`, and
   `ScriptRunner` sub-agents; each resolves `resolveExecutionMode(explicit)` —
   explicit option > `NODETOOL_AGENT_EXECUTION_MODE` > `"tools"`. The setting
-  is registered in the websocket settings registry (Settings UI, group
-  Execution) and mirrored into the environment at server startup. CLI:
+  is registered in the websocket settings registry and exposed in the web
+  Settings UI (General → Execution → "Agent Execution Mode"). The stored value
+  is mirrored into the environment at server startup and again on every write,
+  so switching modes applies to the next run without a restart; a real
+  `NODETOOL_AGENT_EXECUTION_MODE` environment variable pins the mode and wins
+  over both. CLI:
   `nodetool agent run <yaml> --codeact` (YAML: `execution_mode: codeact`).
 - Eval suite `codeact` runs the same offline instrumented cases through either
   executor for a mode comparison: `nodetool eval codeact -p <p> -m <m>`.

packages/websocket/src/settings-registry.ts

@@ -42,19 +42,41 @@ export function getRegisteredSettings(): SettingDefinition[] {
 export const AGENT_EXECUTION_MODE_ENV = "NODETOOL_AGENT_EXECUTION_MODE";
 
 /**
- * Mirror the stored agent execution mode into the environment so the agents
- * package (which resolves NODETOOL_AGENT_EXECUTION_MODE) honors what the
- * Settings UI saved. A real environment variable wins over the stored value;
- * an unavailable settings store leaves the env/default in place.
+ * Whether a real environment variable pins the execution mode. Captured once
+ * at module load, before anything mirrors a stored value into `process.env` —
+ * afterwards the two are indistinguishable, and a deployment that set the mode
+ * in its environment must keep winning over whatever the Settings UI saved.
+ */
+const AGENT_EXECUTION_MODE_PINNED_BY_ENV = Boolean(
+  process.env[AGENT_EXECUTION_MODE_ENV]
+);
+
+/**
+ * Mirror an agent execution mode into the environment so the agents package
+ * (which resolves NODETOOL_AGENT_EXECUTION_MODE) honors what the Settings UI
+ * saved. Called at startup with the stored value and again whenever the
+ * setting is written, so a change applies to the next run instead of waiting
+ * for a restart. Returns false when the value is not a mode, or when an
+ * environment variable pins it.
+ */
+export function setAgentExecutionModeEnv(value: string | null): boolean {
+  if (AGENT_EXECUTION_MODE_PINNED_BY_ENV) return false;
+  const mode = value?.trim().toLowerCase();
+  if (mode !== "codeact" && mode !== "tools") return false;
+  process.env[AGENT_EXECUTION_MODE_ENV] = mode;
+  return true;
+}
+
+/**
+ * Load the stored agent execution mode into the environment at server startup.
+ * A real environment variable wins over the stored value; an unavailable
+ * settings store leaves the env/default in place.
  */
 export async function applyAgentExecutionModeSetting(): Promise<void> {
-  if (process.env[AGENT_EXECUTION_MODE_ENV]) return;
+  if (AGENT_EXECUTION_MODE_PINNED_BY_ENV) return;
   try {
     const setting = await Setting.find("1", AGENT_EXECUTION_MODE_ENV);
-    const value = setting?.value.trim().toLowerCase();
-    if (value === "codeact" || value === "tools") {
-      process.env[AGENT_EXECUTION_MODE_ENV] = value;
-    }
+    setAgentExecutionModeEnv(setting?.value ?? null);
   } catch {
     // Settings store unavailable — the env var / default applies.
   }

packages/websocket/src/trpc/routers/settings.ts

@@ -20,7 +20,9 @@ import { router } from "../index.js";
 import { protectedProcedure } from "../middleware.js";
 import { throwApiError } from "../error-formatter.js";
 import {
+  AGENT_EXECUTION_MODE_ENV,
   getRegisteredSettings,
+  setAgentExecutionModeEnv,
   type SettingWithValue
 } from "../../settings-registry.js";
 import {
@@ -252,6 +254,14 @@ export const settingsRouter = router({
             value: String(value ?? "")
           });
         }
+        // The agents package reads the execution mode off the environment, so
+        // mirror a write immediately — otherwise the switch only takes effect
+        // after a restart.
+        if (AGENT_EXECUTION_MODE_ENV in input.settings) {
+          setAgentExecutionModeEnv(
+            String(input.settings[AGENT_EXECUTION_MODE_ENV] ?? "")
+          );
+        }
       }
 
       // Secrets: skip the unchanged-display placeholder, upsert the rest,

web/src/components/menus/ServerSelectSetting.tsx

@@ -0,0 +1,65 @@
+import React, { useCallback } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { SelectField, Text, type SelectOption } from "../ui_primitives";
+import useRemoteSettingsStore from "../../stores/RemoteSettingStore";
+
+export interface ServerSelectSettingProps {
+  /** Registry env var key (e.g. NODETOOL_AGENT_EXECUTION_MODE). */
+  envVar: string;
+  label: string;
+  description: React.ReactNode;
+  options: readonly SelectOption[];
+  defaultValue: string;
+  id?: string;
+}
+
+/**
+ * A select backed by a server-side registry setting (read/written via tRPC
+ * `settings.list`/`settings.update`), the enum counterpart to
+ * {@link ServerNumberSetting}. These live on the server because the runner
+ * reads them via `getSetting`, not in the local SettingsStore.
+ */
+export const ServerSelectSetting = React.memo(function ServerSelectSetting({
+  envVar,
+  label,
+  description,
+  options,
+  defaultValue,
+  id
+}: ServerSelectSettingProps) {
+  const fetchSettings = useRemoteSettingsStore((s) => s.fetchSettings);
+  const updateSettings = useRemoteSettingsStore((s) => s.updateSettings);
+  // Shared ["settings"] cache: dedupes with the API & Keys tab's own query.
+  useQuery({ queryKey: ["settings"], queryFn: fetchSettings });
+
+  const stored = useRemoteSettingsStore(
+    (s) => s.settings.find((x) => x.env_var === envVar)?.value
+  );
+  const value =
+    stored != null && stored !== "" ? String(stored) : defaultValue;
+
+  const handleChange = useCallback(
+    (next: string) => {
+      if (next === value) return;
+      void updateSettings({ [envVar]: next });
+    },
+    [value, updateSettings, envVar]
+  );
+
+  return (
+    <>
+      <SelectField
+        id={id}
+        label={label}
+        value={value}
+        onChange={handleChange}
+        options={options}
+        variant="standard"
+        size="small"
+      />
+      <Text className="description">{description}</Text>
+    </>
+  );
+});
+
+export default ServerSelectSetting;

web/src/components/menus/SettingsMenu.tsx

@@ -40,6 +40,7 @@ import {
   getDisplayedSettingGroups
 } from "./RemoteSettingsMenu";
 import ServerNumberSetting from "./ServerNumberSetting";
+import ServerSelectSetting from "./ServerSelectSetting";
 import { getAboutSidebarSections } from "./aboutSidebarUtils";
 import DefaultModelsMenu from "./DefaultModelsMenu";
 import MCPSettingsMenu from "./MCPSettingsMenu";
@@ -75,6 +76,11 @@ const CLOSE_BEHAVIOR_OPTIONS = [
   { value: "background", label: "Keep Running in Background" }
 ] as const;
 
+const AGENT_EXECUTION_MODE_OPTIONS = [
+  { value: "tools", label: "Tools (JSON tool calls)" },
+  { value: "codeact", label: "CodeAct (JavaScript actions)" }
+] as const;
+
 const PAN_CONTROLS_OPTIONS = [
   { value: "LMB", label: "Pan canvas" },
   { value: "RMB", label: "Select nodes (box)" }
@@ -840,6 +846,32 @@ function SettingsPage() {
                           description="How many runs of the same workflow may run at once before further runs queue. Applies to concurrent generation (timeline, sketch); canvas runs always stay sequential."
                         />
                       </SearchItem>
+
+                      <SearchItem
+                        search={generalSearch}
+                        keywords="agent execution mode codeact code act tools javascript sandbox action space"
+                      >
+                        <ServerSelectSetting
+                          envVar="NODETOOL_AGENT_EXECUTION_MODE"
+                          id="agent-execution-mode-select"
+                          label="Agent Execution Mode"
+                          defaultValue="tools"
+                          options={AGENT_EXECUTION_MODE_OPTIONS}
+                          description={
+                            <>
+                              How agent steps act on their toolbelt.
+                              <br />
+                              <b>Tools:</b> one JSON tool call per action (the
+                              default).
+                              <br />
+                              <b>CodeAct:</b> each step writes JavaScript that
+                              runs in the sandbox and calls the same tools, so
+                              one action can loop, branch, and combine several
+                              tools.
+                            </>
+                          }
+                        />
+                      </SearchItem>
                     </div>
 
                     <div className="settings-section">

web/src/components/menus/__tests__/ServerSelectSetting.test.tsx

@@ -0,0 +1,96 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ThemeProvider } from "@mui/material/styles";
+import mockTheme from "../../../__mocks__/themeMock";
+import ServerSelectSetting from "../ServerSelectSetting";
+import useRemoteSettingsStore from "../../../stores/RemoteSettingStore";
+
+jest.mock("../../../stores/RemoteSettingStore");
+
+const fetchSettings = jest.fn().mockResolvedValue([]);
+const updateSettings = jest.fn().mockResolvedValue(undefined);
+
+const mockStore = useRemoteSettingsStore as unknown as jest.Mock;
+
+const OPTIONS = [
+  { value: "tools", label: "Tools (JSON tool calls)" },
+  { value: "codeact", label: "CodeAct (JavaScript actions)" }
+] as const;
+
+const setStoredValue = (value: string | undefined) => {
+  const state = {
+    settings:
+      value === undefined
+        ? []
+        : [{ env_var: "NODETOOL_AGENT_EXECUTION_MODE", value }],
+    fetchSettings,
+    updateSettings
+  };
+  mockStore.mockImplementation((selector: (s: typeof state) => unknown) =>
+    selector(state)
+  );
+};
+
+const renderSetting = () =>
+  render(
+    <QueryClientProvider client={new QueryClient()}>
+      <ThemeProvider theme={mockTheme}>
+        <ServerSelectSetting
+          envVar="NODETOOL_AGENT_EXECUTION_MODE"
+          label="Agent Execution Mode"
+          defaultValue="tools"
+          options={OPTIONS}
+          description="How agent steps act on their toolbelt."
+        />
+      </ThemeProvider>
+    </QueryClientProvider>
+  );
+
+describe("ServerSelectSetting", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("falls back to the default when the setting is unset", () => {
+    setStoredValue(undefined);
+    renderSetting();
+    expect(screen.getByRole("combobox")).toHaveTextContent(
+      "Tools (JSON tool calls)"
+    );
+  });
+
+  it("shows the stored value", () => {
+    setStoredValue("codeact");
+    renderSetting();
+    expect(screen.getByRole("combobox")).toHaveTextContent(
+      "CodeAct (JavaScript actions)"
+    );
+  });
+
+  it("writes the picked value back to the server setting", async () => {
+    setStoredValue("tools");
+    renderSetting();
+
+    await userEvent.click(screen.getByRole("combobox"));
+    await userEvent.click(
+      screen.getByRole("option", { name: "CodeAct (JavaScript actions)" })
+    );
+
+    expect(updateSettings).toHaveBeenCalledWith({
+      NODETOOL_AGENT_EXECUTION_MODE: "codeact"
+    });
+  });
+
+  it("does not write when the value is unchanged", async () => {
+    setStoredValue("codeact");
+    renderSetting();
+
+    await userEvent.click(screen.getByRole("combobox"));
+    await userEvent.click(
+      screen.getByRole("option", { name: "CodeAct (JavaScript actions)" })
+    );
+
+    expect(updateSettings).not.toHaveBeenCalled();
+  });
+});