The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat: offer existing Claude and Codex agents a runner upgrade (#17122)
Dotta0f15f82b19df
diff --git a/doc/PRODUCT.md b/doc/PRODUCT.mdindex 1d15c44ed8..5251db8649 100644--- a/doc/PRODUCT.md+++ b/doc/PRODUCT.md@@ -49,6 +49,13 @@ start execution. This preference does not change the org chart or permissions.### Agent Execution+Existing Claude and Codex agents can upgrade from the legacy runner on their+Harness / Runtime page when Paperclip Runner is the qualified default for their+environment. One action saves pending edits and translates compatible settings+while keeping the harness, selected model, account bindings, instructions, and+history. Unsupported settings produce an actionable error without changing the+saved agent. Future runs start fresh sessions.+Paperclip supports several ways to run an agent's heartbeat:1. **Local CLI/session adapters** — Paperclip starts or resumes local coding-tool sessions such as Claude Code, Codex, Gemini, OpenCode, Pi, and Cursor, then tracks the run.diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.mdindex 543fca794b..bdd5ad0090 100644--- a/doc/SPEC-implementation.md+++ b/doc/SPEC-implementation.md@@ -1339,6 +1339,16 @@ Invites tab does not hide this Cloud action.## 10.3 Agents+The Harness / Runtime configuration page offers **Upgrade runner** for existing+legacy Claude and Codex agents when the target environment selects Paperclip+Runner by default. The action uses the normal authorized agent PATCH with+`runner: "paperclip"`, includes pending configuration edits, and retains the+model and compatible settings. A rejected conversion leaves saved configuration+unchanged and identifies unsupported fields. Successful conversion records a+configuration revision, clears incompatible session state, and preserves agent+identity, instruction files, credentials, run policy, and run history. Existing+agents never upgrade merely by visiting or saving unrelated configuration.+The Core setup wizard creates its agent record when the user submits the agentname, before adapter selection, authentication, and runtime configuration.Until the adapter is chosen, the held record uses a provisional adapterdiff --git a/maps/agent-access-map/agents.md b/maps/agent-access-map/agents.mdindex 4e46b700ab..fbbdd91a2f 100644--- a/maps/agent-access-map/agents.md+++ b/maps/agent-access-map/agents.md@@ -105,6 +105,7 @@ API: `present` — representative operation IDs:- `GET /api/agents/{id}/instructions-bundle/file`.- `PUT /api/agents/{id}/instructions-bundle/file`.+- `PATCH /api/agents/{id}` with an explicit `runner: "paperclip"` upgrade.Agent access: `available` — Native read/update/history/restore instruction tools; REST /CLI.@@ -112,6 +113,12 @@ CLI.Policy: Agent creation/configuration uses action grants, resource policies and changeconsent; some controls require a board actor.+The existing-agent upgrade notice uses this configuration PATCH. It does not+grant configuration, account, or environment access. The server resolves the+saved settings under normal company/configuration authorization and rejects+unsupported settings before persistence. Operator browser evidence does not+qualify the agent permission paths for this operation.+Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L1395) atthe reviewed commit above.diff --git a/maps/feature-map/agents.md b/maps/feature-map/agents.mdindex 275a03028b..f9b51ac805 100644--- a/maps/feature-map/agents.md+++ b/maps/feature-map/agents.md@@ -121,6 +121,25 @@ selecting another runner must not silently discard them or change an active run'recorded execution. Keep runner choice in Advanced and verify the next eligiblerun separately from historical transcripts.+Existing legacy Claude and Codex agents on qualified default environments also+show **Upgrade runner** above their configuration. Exercise that action with+pending edits and an environment-variable draft; reopen the page and compare the+saved harness, model, account bindings, instructions, and run policy. Check a+rejected incompatible setting, repair it, and retry. Verify a real task before+and after migration, including its output, preserved history, and fresh session.+The notice must stay absent for native agents, other harnesses, and unsupported+targets. Discovery failure must not imply that an upgrade is available.+Navigate to another agent while an upgrade is pending. Its result must stay with+the original agent, without showing success on the new page or redirecting back.+Focused coverage: [save receipt](../../ui/src/pages/AgentRunnerUpgrade.test.tsx)+and [configuration form](../../ui/src/components/AgentConfigForm.render.test.tsx).++Storybook: [Runner upgrade](../../ui/storybook/stories/agents/codex-runner/upgrade.stories.tsx)+mounts the production page and shell with mutable HTTP fixtures for both harnesses,+pending, failure/retry, incompatible settings, repair, native/unsupported states,+and mobile/light presentation. Fixture success does not establish real migration+or provider execution.+### `organization`Automated: [org chart](../../ui/src/pages/OrgChart.test.tsx) is component evidence. Built-in setup also has [configuration modal tests](../../ui/src/components/ConfigureBuiltInAgentModal.test.tsx).diff --git a/server/src/__tests__/agent-adapter-validation-routes.test.ts b/server/src/__tests__/agent-adapter-validation-routes.test.tsindex f559f74bc8..c18af24c09 100644--- a/server/src/__tests__/agent-adapter-validation-routes.test.ts+++ b/server/src/__tests__/agent-adapter-validation-routes.test.ts@@ -941,6 +941,43 @@ describe("agent routes adapter validation", () => {expect(mockAgentService.update.mock.calls.at(-1)?.[1]).toMatchObject({ adapterConfig: { provider: "codex" } });});+ it.each(["codex_local", "claude_local"])("upgrades an existing %s through runner selection with its saved settings", async adapterType => {+ const existing = await mockAgentService.getById();+ const env = { MIGRATION_MARKER: { type: "plain", value: "keep" } };+ const model = adapterType === "claude_local" ? "claude-sonnet-4-6" : "gpt-5.4";+ mockAgentService.getById.mockResolvedValue({ ...existing, adapterType,+ adapterConfig: { model, effort: "medium", env, promptTemplate: "Keep these instructions", timeoutSec: 180 },+ });+ const app = await createApp();+ const res = await requestApp(app, baseUrl => request(baseUrl)+ .patch("/api/agents/11111111-1111-4111-8111-111111111111").send({ runner: "paperclip" }));+ expect(res.status, JSON.stringify(res.body)).toBe(200);+ expect(mockAgentService.update).toHaveBeenCalledWith(existing.id, expect.objectContaining({+ adapterType: "paperclip_runner",+ adapterConfig: expect.objectContaining({ model, modelReasoningEffort: "medium", env,+ promptTemplate: "Keep these instructions", timeoutSec: 180,+ ...(adapterType === "claude_local" ? { provider: "acpx", acpxAgent: "claude" } : { provider: "codex" }),+ }),+ }), expect.objectContaining({ recordRevision: expect.objectContaining({ source: "patch" }) }));+ const patch = mockAgentService.update.mock.calls[0][1];+ expect(patch).not.toHaveProperty("runner");+ expect(patch.adapterConfig).not.toHaveProperty("effort");+ expect(patch).not.toHaveProperty("runtimeConfig");+ expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ action: "agent.updated", entityId: existing.id }));+ });++ it("leaves a legacy agent unchanged when upgrade settings are incompatible", async () => {+ const existing = await mockAgentService.getById();+ mockAgentService.getById.mockResolvedValue({ ...existing, adapterConfig: { model: "gpt-5.4", extraArgs: ["--search"] } });+ const app = await createApp();+ const res = await requestApp(app, baseUrl => request(baseUrl)+ .patch("/api/agents/11111111-1111-4111-8111-111111111111").send({ runner: "paperclip" }));+ expect(res.status, JSON.stringify(res.body)).toBe(422);+ expect(res.body.details).toMatchObject({ code: "agent_runner_config_incompatible", fields: ["extraArgs"] });+ expect(mockAgentService.update).not.toHaveBeenCalled();+ expect(mockLogActivity).not.toHaveBeenCalled();+ });+it("normalizes legacy skills and permissions when switching to paperclip_runner", async () => {mockInstanceSettingsService.getExperimental.mockResolvedValue({ enableNativeRunner: true });const existing = await mockAgentService.getById();diff --git a/server/src/__tests__/agents-service-clear-error.test.ts b/server/src/__tests__/agents-service-clear-error.test.tsindex 26334aa4b5..500b267167 100644--- a/server/src/__tests__/agents-service-clear-error.test.ts+++ b/server/src/__tests__/agents-service-clear-error.test.ts@@ -47,18 +47,20 @@ describeEmbeddedPostgres("agent service clearError", () => {await tempDb?.cleanup();});- it("resets converted agent sessions while preserving identity, configuration and run history", async () => {+ it.each(["claude_local", "codex_local"])("resets converted %s sessions while preserving identity, configuration and run history", async adapterType => {const companyId = randomUUID();const agentId = randomUUID();const runId = randomUUID();- const config = { cwd: "/tmp/runner-conversion", instructionsFilePath: "/tmp/runner-conversion/AGENTS.md", env: { TEST_KEY: { type: "plain", value: "kept" } } };+ const model = adapterType === "claude_local" ? "claude-sonnet-4-6" : "gpt-5.4";+ const config = { model, cwd: "/tmp/runner-conversion", instructionsFilePath: "/tmp/runner-conversion/AGENTS.md", env: { TEST_KEY: { type: "plain", value: "kept" } } };await db.insert(companies).values({ id: companyId, name: "Conversion", issuePrefix: `T${companyId.slice(0, 6).toUpperCase()}` });- await db.insert(agents).values({ id: agentId, companyId, name: "Claude QA", role: "engineer", adapterType: "claude_local", adapterConfig: config });+ await db.insert(agents).values({ id: agentId, companyId, name: "Migration QA", role: "engineer", adapterType, adapterConfig: config });await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId, invocationSource: "on_demand", status: "succeeded", resultJson: { summary: "history stays" } });- await db.insert(agentTaskSessions).values({ companyId, agentId, adapterType: "claude_local", taskKey: "issue:test", sessionDisplayId: "old-session", lastRunId: runId });- await db.insert(agentRuntimeState).values({ companyId, agentId, adapterType: "claude_local", sessionId: "old-session", stateJson: { old: true }, lastRunId: runId });- const updated = await agentService(db).update(agentId, { adapterType: "paperclip_runner", adapterConfig: { ...config, provider: "acpx", acpxAgent: "claude", model: "custom-claude-model" } });- expect(updated).toMatchObject({ id: agentId, companyId, name: "Claude QA", role: "engineer", adapterConfig: config });+ await db.insert(agentTaskSessions).values({ companyId, agentId, adapterType, taskKey: "issue:test", sessionDisplayId: "old-session", lastRunId: runId });+ await db.insert(agentRuntimeState).values({ companyId, agentId, adapterType, sessionId: "old-session", stateJson: { old: true }, lastRunId: runId });+ const profile = adapterType === "claude_local" ? { provider: "acpx", acpxAgent: "claude" } : { provider: "codex" };+ const updated = await agentService(db).update(agentId, { adapterType: "paperclip_runner", adapterConfig: { ...config, ...profile } });+ expect(updated).toMatchObject({ id: agentId, companyId, name: "Migration QA", role: "engineer", adapterConfig: config });expect(await db.select().from(agentTaskSessions).where(eq(agentTaskSessions.agentId, agentId))).toEqual([]);const [runtime] = await db.select().from(agentRuntimeState).where(eq(agentRuntimeState.agentId, agentId));expect(runtime).toMatchObject({ adapterType: "paperclip_runner", sessionId: null, stateJson: {}, lastRunId: runId });diff --git a/tests/storybook-visual/agent-runner-upgrade.spec.ts b/tests/storybook-visual/agent-runner-upgrade.spec.tsnew file mode 100644index 0000000000..e3101bfdf2--- /dev/null+++ b/tests/storybook-visual/agent-runner-upgrade.spec.ts@@ -0,0 +1,40 @@+import { expect, test } from "@playwright/test";++const stories = ["legacy-codex", "legacy-claude", "upgrade-codex", "upgrade-claude", "upgrading",+ "failure-and-retry", "incompatible-claude-setting", "repair-and-upgrade", "already-upgraded",+ "unavailable-environment", "agent-running", "mobile", "light"];++for (const theme of ["dark", "light"]) {+ for (const story of stories) {+ test(`${story} [${theme}]`, async ({ page }, testInfo) => {+ if (story === "mobile") await page.setViewportSize({ width: 390, height: 844 });+ const errors: string[] = [];+ page.on("pageerror", error => errors.push(error.message));+ const interactive = ["upgrade-codex", "upgrade-claude", "upgrading", "failure-and-retry", "incompatible-claude-setting", "repair-and-upgrade"].includes(story);+ await page.goto(interactive+ ? `/?path=/story/agents-runner-upgrade--${story}&globals=theme:${theme}`+ : `/iframe.html?id=agents-runner-upgrade--${story}&viewMode=story&globals=theme:${theme}`);+ const main = interactive ? page.frameLocator("#storybook-preview-iframe").getByRole("main") : page.getByRole("main");+ await expect(main.getByRole("button", { name: "Model", exact: true })).toBeVisible({ timeout: 20_000 });+ if (interactive) {+ await page.getByRole("tab", { name: /^Interactions/ }).click();+ await expect(page.getByRole("tabpanel", { name: /^Interactions/ }).getByText("Pass", { exact: true })).toBeVisible({ timeout: 20_000 });+ }+ if (["upgrade-codex", "upgrade-claude", "failure-and-retry", "repair-and-upgrade"].includes(story)) {+ await expect(main.getByText("Upgraded to Paperclip Runner.", { exact: true })).toBeVisible();+ await expect(main.getByRole("button", { name: "Upgrade runner", exact: true })).toHaveCount(0);+ } else if (["already-upgraded", "unavailable-environment"].includes(story)) {+ await expect(main.getByText("Upgrade to Paperclip Runner", { exact: true })).toHaveCount(0);+ } else if (story === "upgrading") {+ await expect(main.getByRole("button", { name: "Upgrading…", exact: true })).toBeDisabled();+ } else {+ await expect(main.getByRole("button", { name: "Upgrade runner", exact: true })).toBeEnabled();+ }+ expect(errors).toEqual([]);+ expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true);+ const path = testInfo.outputPath(`${story}-${theme}.png`);+ if (interactive) await page.locator("#storybook-preview-iframe").screenshot({ path });+ else await page.screenshot({ path, fullPage: true });+ });+ }+}diff --git a/ui/src/components/AgentConfigForm.render.test.tsx b/ui/src/components/AgentConfigForm.render.test.tsxindex 032c3979de..c4357cb6c5 100644--- a/ui/src/components/AgentConfigForm.render.test.tsx+++ b/ui/src/components/AgentConfigForm.render.test.tsx@@ -717,6 +717,83 @@ describe("AgentConfigForm environment selector", () => {expect(result.onSave).toHaveBeenCalledWith({ name: "Renamed Cody" });});+ it.each(["codex_local", "claude_local"])("upgrades a saved %s in one click with pending edits", async adapterType => {+ mockAdaptersApi.list.mockResolvedValueOnce([{ type: adapterType, supportedRunners: ["legacy", "paperclip"], defaultRunner: "paperclip" }]);+ const result = await renderForm([], { adapterType, adapterConfig: { model: "existing-model", effort: "high" } });+ roots.push(result.root);+ expect(result.container.textContent).toContain("Upgrade to Paperclip Runner");+ await act(async () => setInputValue(result.container.querySelector<HTMLInputElement>('[placeholder="Agent name"]')!, "Renamed agent"));+ await flushReact();+ await clickByText(result.container, "Upgrade runner");+ expect(result.onSave).toHaveBeenCalledWith({ name: "Renamed agent", runner: "paperclip" });+ });++ it.each(["paperclip_runner", "gemini_local"])("does not offer an upgrade for %s", async adapterType => {+ const result = await renderForm([], { adapterType });+ roots.push(result.root);+ expect(result.container.textContent).not.toContain("Upgrade runner");+ });++ it("includes an uncommitted environment variable draft in an upgrade", async () => {+ mockAdaptersApi.list.mockResolvedValueOnce([{ type: "codex_local", supportedRunners: ["legacy", "paperclip"], defaultRunner: "paperclip" }]);+ const result = await renderForm([], { adapterConfig: { model: "gpt-5.4" } }, { environmentVariablesPlacement: "configuration" });+ roots.push(result.root);+ await clickByText(result.container, "Add variable");+ await act(async () => {+ setInputValue(result.container.querySelector<HTMLInputElement>('input[aria-label="Variable name"]')!, "MIGRATION_MARKER");+ setInputValue(result.container.querySelector<HTMLInputElement>('input[aria-label="Variable value"]')!, "kept");+ });+ await flushReact();+ await clickByText(result.container, "Upgrade runner");+ expect(result.onSave).toHaveBeenCalledWith(expect.objectContaining({ runner: "paperclip", replaceAdapterConfig: true,+ adapterConfig: { model: "gpt-5.4", env: { MIGRATION_MARKER: { type: "plain", value: "kept" } } },+ }));+ });++ it("keeps failed upgrades editable and allows retry", async () => {+ mockAdaptersApi.list.mockResolvedValueOnce([{ type: "codex_local", supportedRunners: ["legacy", "paperclip"], defaultRunner: "paperclip" }]);+ const result = await renderForm([]);+ roots.push(result.root);+ result.onSave.mockRejectedValueOnce(new Error("Paperclip Runner cannot honor these settings: extraArgs."));+ await clickByText(result.container, "Upgrade runner");+ expect(result.container.querySelector('[role="alert"]')?.textContent).toContain("extraArgs");+ expect(result.onSave).toHaveBeenLastCalledWith({ runner: "paperclip" });+ await clickByText(result.container, "Upgrade runner");+ expect(result.onSave).toHaveBeenCalledTimes(2);+ expect(result.container.querySelector('[role="alert"]')).toBeNull();+ });++ it("does not show an earlier agent's upgrade result after navigation", async () => {+ mockAdaptersApi.list.mockResolvedValueOnce([{ type: "codex_local", supportedRunners: ["legacy", "paperclip"], defaultRunner: "paperclip" }]);+ let finishUpgrade!: () => void;+ let changeAgent!: () => void;+ const save = vi.fn(() => new Promise<void>(resolve => { finishUpgrade = resolve; }));+ const container = document.createElement("div");+ document.body.appendChild(container);+ const root = createRoot(container);+ roots.push(root);+ function Fixture() {+ const [agent, setAgent] = useState(() => makeAgent());+ changeAgent = () => setAgent(makeAgent({ id: "agent-2", name: "Another agent" }));+ return <AgentConfigForm mode="edit" agent={agent} onSave={save} hidePromptTemplate />;+ }+ await act(async () => renderFormView(root, createFormQueryClient(), <Fixture />));+ await flushReact();+ await clickByText(container, "Upgrade runner");+ await act(async () => changeAgent());+ await act(async () => finishUpgrade());+ await flushReact();+ expect(container.textContent).not.toContain("Upgraded to Paperclip Runner.");+ expect(findButton(container, "Upgrade runner")).toBeDefined();+ });++ it("does not offer an upgrade when the target only supports Legacy", async () => {+ mockAdaptersApi.list.mockResolvedValueOnce([{ type: "codex_local", supportedRunners: ["legacy"], defaultRunner: "legacy" }]);+ const result = await renderForm([]);+ roots.push(result.root);+ expect(result.container.textContent).not.toContain("Upgrade runner");+ });+it.each(["codex", "claude"].flatMap(harness => ["modelReasoningEffort", "reasoningEffort", "effort"].map(key => ({ harness, key }))))("hydrates saved effort and clears explicit Auto for $harness ($key)", async ({ harness, key }) => {const profile = harness === "codex" ? { provider: "codex", model: "gpt-5.6-sol" } : { provider: "acpx", acpxAgent: "claude", model: "claude-opus-5-5" };const result = await renderForm([], { adapterType: "paperclip_runner", adapterConfig: { ...profile, [key]: "high" } });diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsxindex e1f1223b0b..99eaffea9a 100644--- a/ui/src/components/AgentConfigForm.tsx+++ b/ui/src/components/AgentConfigForm.tsx@@ -475,6 +475,20 @@ export function AgentConfigForm(props: AgentConfigFormProps) {const [overlay, setOverlay] = useState<AgentConfigOverlay>(emptyOverlay);const [environmentDraftDirty, setEnvironmentDraftDirty] = useState(false);const [environmentEditorKey, setEnvironmentEditorKey] = useState(0);+ const [runnerUpgrade, setRunnerUpgrade] = useState<{+ agentId: string;+ status: "pending" | "upgraded" | "failed";+ error?: string;+ } | null>(null);+ const currentRunnerUpgrade = !isCreate && runnerUpgrade?.agentId === props.agent.id ? runnerUpgrade : null;+ const runnerUpgradePending = currentRunnerUpgrade?.status === "pending";+ const runnerUpgraded = currentRunnerUpgrade?.status === "upgraded";+ const runnerUpgradeError = currentRunnerUpgrade?.error;+ useEffect(() => {+ if (!isCreate && props.agent.adapterType !== "paperclip_runner") {+ setRunnerUpgrade(current => current?.agentId === props.agent.id ? null : current);+ }+ }, [isCreate, !isCreate ? props.agent.id : undefined, !isCreate ? props.agent.adapterType : undefined]);const agentRef = useRef<Agent | null>(null);// The overlay snapshot a background account-binding save persisted. The form// stays editable while that save is in flight, so the agent refresh that@@ -623,6 +637,28 @@ export function AgentConfigForm(props: AgentConfigFormProps) {enabled: Boolean(selectedCompanyId),});const runnerAvailability = runnerDiscovery.data?.find(item => item.type === harnessType);+ const showRunnerUpgrade = !isCreate+ && ["codex_local", "claude_local"].includes(props.agent.adapterType)+ && adapterType === props.agent.adapterType+ && !runnerDiscovery.isError+ && runnerAvailability?.defaultRunner === "paperclip";+ const upgradeRunner = async () => {+ if (isCreate || runnerUpgradePending) return;+ const agentId = props.agent.id;+ setRunnerUpgrade({ agentId, status: "pending" });+ try {+ const flushedEnv = flushEnvironmentDraft();+ const nextOverlay = flushedEnv+ ? { ...overlay, adapterConfig: { ...overlay.adapterConfig, env: flushedEnv } }+ : overlay;+ await props.onSave({ ...buildAgentUpdatePatch(props.agent, nextOverlay), runner: "paperclip" });+ setRunnerUpgrade(current => current?.agentId === agentId ? { agentId, status: "upgraded" } : current);+ } catch (error) {+ setRunnerUpgrade(current => current?.agentId === agentId ? {+ agentId, status: "failed", error: error instanceof Error ? error.message : "Could not upgrade this agent. Try again.",+ } : current);+ }+ };const runner: AgentRunnerChoice = isCreate ? props.values.runner ?? "auto" : overlay.runner ?? agentRunner(adapterType);const fieldsAdapterType = isRunnerHarness? (runner === "paperclip" || (runner === "auto" && runnerAvailability?.defaultRunner === "paperclip") ? "paperclip_runner" : harnessType)@@ -1487,6 +1523,27 @@ export function AgentConfigForm(props: AgentConfigFormProps) {}return (+ <div className="space-y-6">+ {showRunnerUpgrade && !runnerUpgraded ? (+ <div className="space-y-3 rounded-lg border border-border bg-muted/30 p-4">+ <div className="flex flex-col items-start justify-between gap-4 sm:flex-row sm:items-center">+ <div className="min-w-0 flex-1 space-y-1">+ <p className="text-sm font-medium">Upgrade to Paperclip Runner</p>+ <p className="text-sm text-muted-foreground">+ Keep {harnessType === "claude_local" ? "Claude" : "Codex"}, your model, account, and compatible settings.+ New sessions start fresh; past runs stay available.+ </p>+ {isDirty ? <p className="text-xs text-muted-foreground">Your unsaved changes will be included.</p> : null}+ </div>+ <Button size="sm" className="self-end sm:self-auto" onClick={upgradeRunner} disabled={runnerUpgradePending || (!isCreate && props.isSaving)}>+ {runnerUpgradePending ? <Loader2 className="size-4 animate-spin" /> : null}+ {runnerUpgradePending ? "Upgrading…" : "Upgrade runner"}+ </Button>+ </div>+ {runnerUpgradeError ? <p role="alert" className="text-sm text-destructive">{runnerUpgradeError}</p> : null}+ </div>+ ) : null}+ {runnerUpgraded ? <p role="status" className="text-sm text-muted-foreground">Upgraded to Paperclip Runner.</p> : null}<ConfigSections order={props.sectionOrder} className={cn("relative", cards && "space-y-6")}>{/* ---- Floating Save button (edit mode, when dirty) ---- */}{isDirty && !props.hideInlineSave && (@@ -2240,6 +2297,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {/>)}</ConfigSections>+ </div>);}diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsxindex f659386cc1..596c11fcb8 100644--- a/ui/src/pages/AgentDetail.tsx+++ b/ui/src/pages/AgentDetail.tsx@@ -2048,16 +2048,18 @@ export function ConfigurationTab({});const updateAgent = useMutation({- mutationFn: (data: Record<string, unknown>) => agentsApi.update(agent.id, data, companyId),+ mutationFn: ({ target, patch }: { target: AgentDetailRecord; patch: Record<string, unknown> }) =>+ agentsApi.update(target.id, patch, target.companyId),onMutate: () => {setAwaitingRefreshAfterSave(true);},- onSuccess: (updated) => {- queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agent.id) });- queryClient.invalidateQueries({ queryKey: queryKeys.agents.configRevisions(agent.id) });- queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(agent.companyId) });- if (!syncAgentRouteAfterRename(queryClient, navigate, agent, updated, urlTab ?? content)) {- queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agent.urlKey) });+ onSuccess: (updated, { target }) => {+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(target.id) });+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.configRevisions(target.id) });+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(target.companyId) });+ if (lastAgentRef.current.id !== target.id+ || !syncAgentRouteAfterRename(queryClient, navigate, target, updated, urlTab ?? content)) {+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(target.urlKey) });}pushToast({ title: "Agent saved", tone: "success" });},@@ -2113,7 +2115,7 @@ export function ConfigurationTab({{content !== "permissions" ? <AgentConfigFormmode="edit"agent={agent}- onSave={(patch) => updateAgent.mutateAsync(patch)}+ onSave={(patch) => updateAgent.mutateAsync({ target: agent, patch })}isSaving={isConfigSaving}adapterModels={adapterModels}onDirtyChange={onDirtyChange}diff --git a/ui/src/pages/AgentRunnerUpgrade.test.tsx b/ui/src/pages/AgentRunnerUpgrade.test.tsxnew file mode 100644index 0000000000..95301725ee--- /dev/null+++ b/ui/src/pages/AgentRunnerUpgrade.test.tsx@@ -0,0 +1,64 @@+// @vitest-environment jsdom++import { act } from "react";+import { createRoot } from "react-dom/client";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { afterEach, expect, it, vi } from "vitest";+import type { AgentDetail } from "@paperclipai/shared";+import { ConfigurationTab } from "./AgentDetail";++const mocks = vi.hoisted(() => ({ update: vi.fn(), navigate: vi.fn(), toast: vi.fn() }));+vi.mock("../api/agents", async importOriginal => {+ const actual = await importOriginal<typeof import("../api/agents")>();+ return { ...actual, agentsApi: { ...actual.agentsApi, update: mocks.update, adapterModels: async () => [] } };+});+vi.mock("@/lib/router", async importOriginal => {+ const actual = await importOriginal<typeof import("@/lib/router")>();+ return { ...actual, useNavigate: () => mocks.navigate, useParams: () => ({ tab: "runtime" }) };+});+vi.mock("../context/ToastContext", async importOriginal => {+ const actual = await importOriginal<typeof import("../context/ToastContext")>();+ return { ...actual, useToastActions: () => ({ pushToast: mocks.toast }) };+});+vi.mock("../components/AgentConfigForm", () => ({+ AgentConfigForm: ({ onSave }: { onSave: (patch: Record<string, unknown>) => Promise<unknown> }) =>+ <button onClick={() => { void onSave({ runner: "paperclip" }); }}>Upgrade runner</button>,+}));++function agent(id: string): AgentDetail {+ return { id, companyId: "company-1", name: id, urlKey: id, role: "engineer", permissions: {},+ adapterType: "codex_local", adapterConfig: {}, runtimeConfig: {}, chainOfCommand: [] } as unknown as AgentDetail;+}++afterEach(() => vi.clearAllMocks());++it("keeps an upgrade receipt on its original agent when navigation changes the configuration page", async () => {+ const original = agent("original-agent");+ let finish!: (updated: AgentDetail) => void;+ mocks.update.mockReturnValue(new Promise<AgentDetail>(resolve => { finish = resolve; }));+ const client = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } });+ const invalidate = vi.spyOn(client, "invalidateQueries");+ const container = document.createElement("div");+ document.body.appendChild(container);+ const root = createRoot(container);+ const noop = () => {};+ const render = (value: AgentDetail) => root.render(<QueryClientProvider client={client}>+ <ConfigurationTab agent={value} companyId={value.companyId} onDirtyChange={noop} onSaveActionChange={noop}+ onCancelActionChange={noop} onSavingChange={noop} updatePermissions={{ mutate: noop, isPending: false }} />+ </QueryClientProvider>);+ try {+ await act(async () => render(original));+ await act(async () => container.querySelector("button")!.click());+ await act(async () => render(agent("other-agent")));+ await act(async () => finish({ ...original, adapterType: "paperclip_runner", adapterConfig: { provider: "codex" } }));+ await act(async () => { await new Promise(resolve => setTimeout(resolve, 0)); });+ expect(mocks.update).toHaveBeenCalledWith(original.id, { runner: "paperclip" }, original.companyId);+ expect(mocks.navigate).not.toHaveBeenCalled();+ expect(invalidate).toHaveBeenCalledWith({ queryKey: ["agents", "detail", original.id] });+ expect(invalidate).not.toHaveBeenCalledWith({ queryKey: ["agents", "detail", "other-agent"] });+ } finally {+ await act(async () => root.unmount());+ client.clear();+ container.remove();+ }+});diff --git a/ui/storybook/stories/agents/codex-runner/upgrade.stories.tsx b/ui/storybook/stories/agents/codex-runner/upgrade.stories.tsxnew file mode 100644index 0000000000..4aea50f838--- /dev/null+++ b/ui/storybook/stories/agents/codex-runner/upgrade.stories.tsx@@ -0,0 +1,140 @@+import type { Meta, StoryObj } from "@storybook/react-vite";+import { expect, userEvent, within, waitFor } from "storybook/test";+import { Route, Routes } from "@/lib/router";+import { AgentDetail } from "@/pages/AgentDetail";+import { Layout } from "@/components/Layout.production";+import { PluginLauncherProvider } from "@/plugins/launchers";+import { storybookAgents } from "../../../fixtures/paperclipData";+import { resetOnboardingFixtureState, setOnboardingFixtureState } from "../../../fixtures/onboardingEnvironment";++type Scenario = {+ harness?: "codex_local" | "claude_local";+ failOnce?: boolean;+ incompatible?: boolean;+ unavailable?: boolean;+ upgraded?: boolean;+ running?: boolean;+ delay?: number;+};++function installUpgradeFixture({ harness = "codex_local", failOnce = false, incompatible = false, unavailable = false, upgraded = false, running = false, delay = 0 }: Scenario = {}) {+ resetOnboardingFixtureState();+ setOnboardingFixtureState({ environments: "local", authSignal: "present", localLoginStatus: "ready" });+ const profile = harness === "claude_local" ? { provider: "acpx", acpxAgent: "claude" } : { provider: "codex" };+ let agent = { ...storybookAgents[0]!, urlKey: "migration-agent", name: harness === "claude_local" ? "ClaudeWriter" : "CodexCoder",+ status: running ? "running" : "idle", lifecycleState: "ready", defaultEnvironmentId: null,+ adapterType: upgraded ? "paperclip_runner" : harness,+ adapterConfig: { model: harness === "claude_local" ? "claude-sonnet-4-6" : "gpt-5.4", modelReasoningEffort: "medium", timeoutSec: 180,+ ...(upgraded ? profile : {}), ...(incompatible ? { chrome: true } : {}), env: { MIGRATION_MARKER: { type: "plain", value: "keep-this-setting" } } },+ runtimeConfig: { heartbeat: { enabled: false, wakeOnDemand: true } },+ chainOfCommand: [], access: { canAssignTasks: true, taskAssignSource: "explicit_grant", membership: null, grants: [] },+ };+ const previous = window.fetch;+ const fixtureFetch: typeof fetch = async (input, init) => {+ const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url, window.location.origin);+ const method = init?.method ?? "GET";+ if (url.pathname === "/api/adapters") {+ const response = await previous(input, init);+ return Response.json((await response.json()).map((item: { type: string }) => ["codex_local", "claude_local"].includes(item.type)+ ? { ...item, defaultRunner: unavailable ? "legacy" : "paperclip", supportedRunners: unavailable ? ["legacy"] : ["legacy", "paperclip"] } : item));+ }+ if (url.pathname === `/api/companies/${agent.companyId}/agents`) {+ return Response.json(storybookAgents.map(item => item.id === agent.id ? agent : item));+ }+ if ([`/api/agents/${agent.id}`, `/api/agents/${agent.urlKey}`].includes(url.pathname)) {+ if (method === "PATCH") {+ const patch = JSON.parse(String(init?.body ?? "{}"));+ if (delay) await new Promise(resolve => setTimeout(resolve, delay));+ if (patch.runner !== "paperclip") return Response.json({ error: "This fixture expects an explicit runner upgrade." }, { status: 422 });+ if (failOnce) {+ failOnce = false;+ return Response.json({ error: "Could not save this agent. Try again." }, { status: 503 });+ }+ if (incompatible && (patch.adapterConfig?.chrome ?? agent.adapterConfig.chrome) === true) return Response.json({ error: "Paperclip Runner cannot honor these settings: chrome. Remove them or select Legacy runner in Advanced." }, { status: 422 });+ const { runner: _runner, replaceAdapterConfig: _replace, adapterConfig, ...rest } = patch;+ agent = { ...agent, ...rest, adapterType: "paperclip_runner", adapterConfig: { ...agent.adapterConfig, ...adapterConfig, ...profile } };+ }+ return Response.json(agent);+ }+ return previous(input, init);+ };+ window.fetch = fixtureFetch;+ return () => { if (window.fetch === fixtureFetch) window.fetch = previous; resetOnboardingFixtureState(); };+}++function UpgradePage() {+ return <PluginLauncherProvider><Routes>+ <Route path="/:companyPrefix" element={<Layout />}>+ <Route path="agents/:agentId/:tab?" element={<AgentDetail />} />+ </Route>+ </Routes></PluginLauncherProvider>;+}++const meta = {+ id: "agents-runner-upgrade",+ title: "Agents and reusable capabilities/Hiring, configuration, and organization/Agents/Runner upgrade",+ component: UpgradePage,+ parameters: {+ layout: "fullscreen",+ initialEntries: ["/PAP/agents/migration-agent/runtime"],+ docs: { description: { component: "Existing Codex and Claude agents in the production agent page and app shell. The upgrade PATCH and subsequent reads use a mutable HTTP fixture. These stories demonstrate the notice, save, retry and refreshed form; real migration and provider proof are separate checks." } },+ paperclip: {+ capabilities: ["agents/instructions", "runs-adapters/validation"],+ status: "current",+ implementation: "production",+ boundary: "fixtures",+ notes: "Production AgentDetail, ConfigurationTab, AgentConfigForm and app shell. Mutable fixtures simulate upgrade persistence and rejection; no provider, credential access, session reset or durable database is exercised.",+ },+ },+ beforeEach: ({ parameters }) => installUpgradeFixture(parameters.runnerUpgrade),+ render: () => <UpgradePage />,+} satisfies Meta<typeof UpgradePage>;+export default meta;+type Story = StoryObj<typeof meta>;++export const LegacyCodex: Story = {};+export const LegacyClaude: Story = { parameters: { runnerUpgrade: { harness: "claude_local" } } };+export const Upgrading: Story = { parameters: { runnerUpgrade: { delay: 60_000 } }, play: async ({ canvasElement }) => {+ const page = within(canvasElement);+ await userEvent.click(await page.findByRole("button", { name: "Upgrade runner" }));+ await expect(await page.findByRole("button", { name: "Upgrading…" })).toBeDisabled();+} };+export const UpgradeCodex: Story = { play: async ({ canvasElement }) => {+ const page = within(canvasElement);+ await userEvent.click(await page.findByRole("button", { name: "Upgrade runner" }));+ await expect(await page.findByText("Upgraded to Paperclip Runner.")).toBeVisible();+ await waitFor(() => expect(page.queryByRole("button", { name: "Upgrade runner" })).not.toBeInTheDocument());+ await expect(await page.findByRole("button", { name: /^Model$/ })).toHaveTextContent(/gpt-5.4/i);+} };+export const UpgradeClaude: Story = { ...UpgradeCodex, parameters: { runnerUpgrade: { harness: "claude_local" } }, play: async ({ canvasElement }) => {+ const page = within(canvasElement);+ await userEvent.click(await page.findByRole("button", { name: "Upgrade runner" }));+ await expect(await page.findByText("Upgraded to Paperclip Runner.")).toBeVisible();+ await expect(await page.findByRole("button", { name: /^Model$/ })).toHaveTextContent(/claude[- ]sonnet[- ]4[-.]6/i);+} };+export const FailureAndRetry: Story = { parameters: { runnerUpgrade: { failOnce: true } }, play: async ({ canvasElement }) => {+ const page = within(canvasElement);+ await userEvent.click(await page.findByRole("button", { name: "Upgrade runner" }));+ await expect(await page.findByRole("alert")).toHaveTextContent("Could not save this agent");+ await userEvent.click(page.getByRole("button", { name: "Upgrade runner" }));+ await expect(await page.findByText("Upgraded to Paperclip Runner.")).toBeVisible();+} };+export const IncompatibleClaudeSetting: Story = { parameters: { runnerUpgrade: { harness: "claude_local", incompatible: true } }, play: async ({ canvasElement }) => {+ const page = within(canvasElement);+ await userEvent.click(await page.findByRole("button", { name: "Upgrade runner" }));+ await expect(await page.findByRole("alert")).toHaveTextContent("chrome");+ await expect(page.getByRole("switch", { name: "Enable Chrome" })).toBeChecked();+} };+export const RepairAndUpgrade: Story = { ...IncompatibleClaudeSetting, play: async context => {+ await IncompatibleClaudeSetting.play!(context);+ const page = within(context.canvasElement);+ await userEvent.click(page.getByRole("switch", { name: "Enable Chrome" }));+ await expect(page.getByText("Your unsaved changes will be included.")).toBeVisible();+ await userEvent.click(page.getByRole("button", { name: "Upgrade runner" }));+ await expect(await page.findByText("Upgraded to Paperclip Runner.")).toBeVisible();+} };+export const AlreadyUpgraded: Story = { parameters: { runnerUpgrade: { upgraded: true } } };+export const UnavailableEnvironment: Story = { parameters: { runnerUpgrade: { unavailable: true } } };+export const AgentRunning: Story = { parameters: { runnerUpgrade: { running: true } } };+export const Mobile: Story = { globals: { viewport: { value: "mobile1", isRotated: false } } };+export const Light: Story = { globals: { theme: "light" } };