feat(agents): bulk edit agent runtime, model, concurrency, args, and env

Add a Bulk edit dialog so workspace owners/admins can update shared launch
settings across selected agents or every active agent in a workspace — runtime,
model, max concurrent tasks, custom CLI args, and environment variable keys —
with each field opt-in (disabled fields are left unchanged). Single-agent and
bulk "clear model" both persist SQL NULL, falling back to the runtime/CLI
default. Changing runtime/model only affects new tasks; Multica keeps no
workspace-level active engine.

DB / API / server:
- agent.sql + generated: ListAgentsForUpdate, ListAgentsByIDsForUpdate (write),
  ListAgentsByIDs (read, non-locking — no per-agent N+1), ClearAgentModel.
- handler: BulkUpdateAgents + ListBulkAgentEnvKeys (owner/admin only, agent
  actor rejected 403, one transaction across all targets, env-change audit by
  key name only). Env values are never returned, logged, or surfaced — only key
  names and counts. patchAgentEnv preserves a value via a sentinel without
  reading it.

Core:
- typed API client (parseWithFallback + zod, typed EMPTY_* fallbacks) and a
  local presets store via StorageAdapter (env values never persisted).

UI:
- bulk-edit dialog + agents-page entry points; affected-count banner uses the
  semantic warning token; all copy via i18n in en/ja/ko/zh-Hans.

Docs:
- agents-runtime-model.mdx + nav.

Tests:
- handler coverage (selected/all, clear-model->NULL, archived rejection, UUID
  dedup, agent-actor 403, env keys-only / no value leak), core/views vitest,
  e2e/agents-bulk-edit.spec.ts. Shared e2e infra hardened for per-worker
  isolation and onboarding-v2.

Author: “646826”

apps/docs/content/docs/agents-create.mdx

@@ -52,6 +52,8 @@ Most AI coding tools support model selection (for example, Claude Code lets you
 
 Changing the model **only applies to new tasks**. Already-dispatched tasks continue with the model that was locked in at dispatch time.
 
+To update runtime, model, concurrency, CLI args, or environment keys across selected agents or every active agent, see [Bulk edit agents](/agents-runtime-model).
+
 ## Custom environment variables (custom_env)
 
 **Custom environment variables** (`custom_env`) let you inject extra env vars at task execution time — typical uses are API keys or switching the upstream endpoint:
@@ -123,5 +125,6 @@ Archived agents can't be assigned new tasks.
 ## Next steps
 
 - [Skills](/skills) — attach knowledge packs to an agent
+- [Bulk edit agents](/agents-runtime-model) — update runtime, model, concurrency, CLI args, or environment keys across agents
 - [AI coding tools comparison](/providers) — full capability matrix across all 12 tools
 - [Assigning issues to agents](/assigning-issues) — put your new agent to work

apps/docs/content/docs/agents-runtime-model.mdx

@@ -0,0 +1,101 @@
+---
+title: Bulk edit agents
+description: Update runtime, model, concurrency, CLI args, or environment keys for selected agents or every active agent in a workspace.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Bulk edit lets workspace owners and admins update shared launch settings across selected agents, or across every active agent in a workspace.
+
+Each field is opt-in. Disabled fields are left unchanged, so you can update only the model, only CLI args, only environment keys, or any supported combination.
+
+## What you can change
+
+| Field | Behavior |
+|---|---|
+| Runtime | Moves targeted agents to another runtime in the same workspace |
+| Model | Pins a model, or clears the override when left empty |
+| Max concurrent tasks | Replaces the per-agent concurrency limit |
+| Custom args | Adds, replaces, or removes exact CLI argument tokens |
+| Environment variables | Sets/replaces key values or removes keys without reading existing values |
+
+An agent's runtime decides which AI coding tool runs its tasks. The optional **model** field is passed to that tool when it supports per-agent model selection.
+
+Multica does not store a workspace-wide active provider. Each agent points to a runtime, and the selected runtime's provider is used for new tasks.
+
+Changing runtime or model only affects **new tasks**. Tasks that were already claimed or running continue with the runtime and model resolved when they started.
+
+<Callout type="warning">
+Bulk edit changes agent launch configuration. It does not change retry, failover, billing, token refresh, or account-management behavior.
+</Callout>
+
+## Bulk edit selected agents
+
+1. Go to the **Agents** page.
+2. Select the active agents you want to update.
+3. Click **Bulk edit selected**.
+4. Enable only the fields you want to change.
+5. Review the affected-agent count.
+6. Click **Apply**.
+
+Selected archived agents are rejected by the server. If an agent is archived before the update is applied, the server refuses that target instead of changing an archived agent.
+
+## Bulk edit all active agents
+
+Workspace owners and admins can update every active agent at once:
+
+1. Go to the **Agents** page.
+2. Click **Bulk edit agents** in the header.
+3. Enable only the fields you want to change.
+4. Enter the new values or operations.
+5. Review the affected-agent count.
+6. Click **Apply**.
+
+This updates every **non-archived** agent in the workspace. Archived agents are left unchanged.
+
+<Callout type="info">
+The count shown before applying is the current number of active agents in the UI. The success toast uses the server-returned update count, which is the authoritative number of agents changed.
+</Callout>
+
+## Runtime and model
+
+When you update runtime or model, Multica stores:
+
+| Field | Meaning |
+|---|---|
+| `runtime_id` | The runtime that will claim new tasks for the agent |
+| `runtime_mode` | The runtime mode copied from the selected runtime |
+| `model` | The optional model to pass to that runtime's provider |
+
+`runtime_id` is the provider source for new tasks. The model is optional; leaving it empty lets the runtime or CLI choose its default.
+
+The target runtime must belong to the workspace. Workspace owners and admins can use any workspace runtime in the bulk action.
+
+## Custom args
+
+Custom arg operations apply to each targeted agent's existing `custom_args`:
+
+- **Add** appends the arg when it is not already present.
+- **Replace** changes exact matching arg tokens.
+- **Remove** deletes exact matching arg tokens.
+
+Multi-token input is split the same way as the agent **Custom Args** tab. For example, `--max-turns 100` becomes two args: `--max-turns` and `100`.
+
+## Environment keys
+
+The bulk dialog can suggest existing environment keys, but it never loads existing values. This keeps secret values out of the bulk UI.
+
+- **Set / replace** adds a missing key or replaces an existing value.
+- **Remove** deletes a key from agents where it exists.
+- If the same key appears more than once in the form, the last operation wins.
+
+Local presets can remember field choices, runtime, model, custom arg operations, and environment key operations for the current browser and workspace. Presets do **not** save environment values; values must be entered again after loading a preset.
+
+## Permissions
+
+Bulk edit is available to workspace owners and admins. Individual agent updates still follow the normal agent-management rules: workspace owners and admins can manage any agent, and an agent owner can manage their own agent.
+
+## Next
+
+- [Create and configure an agent](/agents-create) — all agent settings
+- [AI coding tools matrix](/providers) — provider capabilities and model-selection differences

apps/docs/content/docs/meta.json

@@ -15,6 +15,7 @@
     "---Agents---",
     "agents",
     "agents-create",
+    "agents-runtime-model",
     "skills",
     "squads",
     "---How agents run---",

packages/core/agents/stores/bulk-edit-presets-store.test.ts

@@ -0,0 +1,101 @@
+// @vitest-environment jsdom
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { setCurrentWorkspace } from "../../platform/workspace-storage";
+import { useAgentBulkEditPresetsStore } from "./bulk-edit-presets-store";
+
+const flush = () => new Promise((resolve) => queueMicrotask(() => resolve(null)));
+
+beforeAll(() => {
+  if (typeof globalThis.localStorage?.clear !== "function") {
+    const values = new Map<string, string>();
+    const storage: Storage = {
+      get length() { return values.size; },
+      clear: () => values.clear(),
+      getItem: (k) => values.get(k) ?? null,
+      key: (i) => Array.from(values.keys())[i] ?? null,
+      removeItem: (k) => { values.delete(k); },
+      setItem: (k, v) => { values.set(k, v); },
+    };
+    Object.defineProperty(globalThis, "localStorage", { configurable: true, value: storage });
+    Object.defineProperty(window, "localStorage", { configurable: true, value: storage });
+  }
+});
+
+beforeEach(() => {
+  localStorage.clear();
+  setCurrentWorkspace(null, null);
+  useAgentBulkEditPresetsStore.setState({ presets: [] });
+});
+
+afterEach(() => {
+  setCurrentWorkspace(null, null);
+});
+
+describe("useAgentBulkEditPresetsStore", () => {
+  it("persists bulk edit presets under the workspace namespace", async () => {
+    setCurrentWorkspace("acme", "ws_a");
+    await flush();
+
+    useAgentBulkEditPresetsStore.getState().savePreset("Claude local", {
+      model: "claude-sonnet-4",
+      customArgsPatch: [
+        { action: "add", value: "--permission-mode" },
+        { action: "add", value: "acceptEdits" },
+      ],
+      env: [{ action: "remove", key: "OLD_KEY" }],
+    });
+
+    const raw = localStorage.getItem("multica_agent_bulk_edit_presets:acme");
+    expect(raw).not.toBeNull();
+    expect(JSON.parse(raw as string).state.presets).toHaveLength(1);
+  });
+
+  it("does not persist env values in local presets", async () => {
+    setCurrentWorkspace("acme", "ws_a");
+    await flush();
+
+    useAgentBulkEditPresetsStore.getState().savePreset("Secret skeleton", {
+      env: [
+        { action: "set", key: "ANTHROPIC_API_KEY", value: "sk-secret" },
+        { action: "remove", key: "OLD_KEY" },
+      ] as never,
+    });
+
+    const preset = useAgentBulkEditPresetsStore.getState().presets[0]!;
+    expect(preset.patch.env).toEqual([
+      { action: "set", key: "ANTHROPIC_API_KEY" },
+      { action: "remove", key: "OLD_KEY" },
+    ]);
+    expect(localStorage.getItem("multica_agent_bulk_edit_presets:acme")).not.toContain("sk-secret");
+  });
+
+  it("sanitizes custom arg and env operations before persisting a preset", async () => {
+    setCurrentWorkspace("acme", "ws_a");
+    await flush();
+
+    useAgentBulkEditPresetsStore.getState().savePreset("  Clean preset  ", {
+      customArgsPatch: [
+        { action: "add", value: " --verbose " },
+        { action: "replace", value: " --old ", replacement: " --new " },
+        { action: "replace", value: "--missing-replacement", replacement: " " },
+        { action: "remove", value: " " },
+      ],
+      env: [
+        { action: "set", key: " API_KEY " },
+        { action: "remove", key: " OLD_KEY " },
+        { action: "set", key: " " },
+      ],
+    } as never);
+
+    const preset = useAgentBulkEditPresetsStore.getState().presets[0]!;
+    expect(preset.name).toBe("Clean preset");
+    expect(preset.patch.customArgsPatch).toEqual([
+      { action: "add", value: "--verbose", replacement: undefined },
+      { action: "replace", value: "--old", replacement: "--new" },
+    ]);
+    expect(preset.patch.env).toEqual([
+      { action: "set", key: "API_KEY" },
+      { action: "remove", key: "OLD_KEY" },
+    ]);
+  });
+});

packages/core/agents/stores/bulk-edit-presets-store.ts

@@ -0,0 +1,133 @@
+"use client";
+
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+import { createSafeId } from "../../utils";
+import {
+  createWorkspaceAwareStorage,
+  registerForWorkspaceRehydration,
+} from "../../platform/workspace-storage";
+import { defaultStorage } from "../../platform/storage";
+
+export interface AgentBulkEditPresetEnvOperation {
+  action: "set" | "remove";
+  key: string;
+}
+
+export interface AgentBulkEditPresetCustomArgOperation {
+  action: "add" | "replace" | "remove";
+  value: string;
+  replacement?: string;
+}
+
+export interface AgentBulkEditPresetPatch {
+  runtimeId?: string;
+  model?: string;
+  maxConcurrentTasks?: number;
+  customArgsPatch?: AgentBulkEditPresetCustomArgOperation[];
+  env?: AgentBulkEditPresetEnvOperation[];
+}
+
+export interface AgentBulkEditPreset {
+  id: string;
+  name: string;
+  patch: AgentBulkEditPresetPatch;
+  updatedAt: number;
+}
+
+interface AgentBulkEditPresetsState {
+  presets: AgentBulkEditPreset[];
+  savePreset: (name: string, patch: AgentBulkEditPresetPatch) => string;
+  removePreset: (id: string) => void;
+}
+
+const MAX_PRESETS = 12;
+
+export const useAgentBulkEditPresetsStore = create<AgentBulkEditPresetsState>()(
+  persist(
+    (set) => ({
+      presets: [],
+      savePreset: (name, patch) => {
+        const id = createSafeId();
+        const preset: AgentBulkEditPreset = {
+          id,
+          name: name.trim(),
+          patch: sanitizePresetPatch(patch),
+          updatedAt: Date.now(),
+        };
+        set((state) => ({
+          presets: [
+            preset,
+            ...state.presets.filter((existing) => existing.name !== preset.name),
+          ].slice(0, MAX_PRESETS),
+        }));
+        return id;
+      },
+      removePreset: (id) =>
+        set((state) => ({
+          presets: state.presets.filter((preset) => preset.id !== id),
+        })),
+    }),
+    {
+      name: "multica_agent_bulk_edit_presets",
+      storage: createJSONStorage(() => createWorkspaceAwareStorage(defaultStorage)),
+      partialize: (state) => ({ presets: state.presets }),
+      merge: (persisted, current) => {
+        const raw = (persisted as Partial<AgentBulkEditPresetsState> | undefined)?.presets;
+        if (!raw) return { ...current, presets: [] };
+        return {
+          ...current,
+          presets: raw
+            .map((preset) => ({
+              ...preset,
+              patch: sanitizePresetPatch(preset.patch),
+            }))
+            .slice(0, MAX_PRESETS),
+        };
+      },
+    },
+  ),
+);
+
+registerForWorkspaceRehydration(() => useAgentBulkEditPresetsStore.persist.rehydrate());
+
+function sanitizePresetPatch(patch: AgentBulkEditPresetPatch): AgentBulkEditPresetPatch {
+  const out: AgentBulkEditPresetPatch = {};
+
+  if (patch.runtimeId !== undefined) out.runtimeId = patch.runtimeId;
+  if (patch.model !== undefined) out.model = patch.model;
+  if (patch.maxConcurrentTasks !== undefined) {
+    out.maxConcurrentTasks = patch.maxConcurrentTasks;
+  }
+  if (patch.customArgsPatch !== undefined) {
+    const customArgsPatch = patch.customArgsPatch
+      .map((op) => ({
+        action: normalizeCustomArgAction(op.action),
+        value: op.value.trim(),
+        replacement: op.replacement?.trim(),
+      }))
+      .filter((op) =>
+        op.value.length > 0 &&
+        (op.action !== "replace" || (op.replacement?.length ?? 0) > 0),
+      );
+    if (customArgsPatch.length > 0) out.customArgsPatch = customArgsPatch;
+  }
+  if (patch.env !== undefined) {
+    const env = patch.env
+      .map((op) => ({
+        action: op.action === "remove" ? "remove" as const : "set" as const,
+        key: op.key.trim(),
+      }))
+      .filter((op) => op.key.length > 0);
+    if (env.length > 0) out.env = env;
+  }
+
+  return out;
+}
+
+function normalizeCustomArgAction(
+  action: AgentBulkEditPresetCustomArgOperation["action"],
+): AgentBulkEditPresetCustomArgOperation["action"] {
+  if (action === "replace" || action === "remove") return action;
+  return "add";
+}

packages/core/agents/stores/index.ts

@@ -15,3 +15,9 @@ export {
   useTranscriptViewStore,
   type TranscriptSortDirection,
 } from "./transcript-view-store";
+export {
+  useAgentBulkEditPresetsStore,
+  type AgentBulkEditPreset,
+  type AgentBulkEditPresetPatch,
+  type AgentBulkEditPresetEnvOperation,
+} from "./bulk-edit-presets-store";