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
fix(agents): allow runner qualification with agent configuration permission (#17448)
Dotta0eb2c964a710
diff --git a/doc/PRODUCT.md b/doc/PRODUCT.mdindex ffda2b04cd..4808641189 100644--- a/doc/PRODUCT.md+++ b/doc/PRODUCT.md@@ -56,6 +56,11 @@ while keeping the harness, selected model, account bindings, instructions, andhistory. Unsupported settings produce an actionable error without changing thesaved agent. Future runs start fresh sessions.+Qualifying an existing agent's sandbox for that upgrade uses the same agent+configuration permission as saving the upgrade. The server checks the saved+computer and its company binding. Company owners do not need instance-admin+access for this step; general instance environment management remains restricted.+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/maps/agent-access-map/agents.md b/maps/agent-access-map/agents.mdindex 8599a70e39..efc593ec74 100644--- a/maps/agent-access-map/agents.md+++ b/maps/agent-access-map/agents.md@@ -106,6 +106,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.+- `POST /api/agents/{id}/qualify-runner` to qualify the saved effective sandbox before upgrading.- `PATCH /api/agents/{id}` with `runtimeSettings: { harness, model?, aiConnection?, expected: { model, aiConnection } }` for a narrow roster edit. Each request handles one agent; the UI batches at most four writes and collects per-agent outcomes.Agent access: `available` — Native read/update/history/restore instruction tools; REST /@@ -125,9 +126,13 @@ The existing-agent upgrade notice uses this configuration PATCH. It does notgrant configuration, account, or environment access. The server resolves thesaved settings under normal company/configuration authorization. Obsolete Claudetuning fields are removed with `configurationWarnings`; security incompatibilities-remain errors. Unqualified sandbox upgrades first use the existing-`POST /api/environments/{id}/probe?companyId=...`, retaining its instance-admin-authorization and company-scoped qualification. No probe runs merely on page load. Operator browser evidence does not+remain errors. Unqualified sandbox upgrades first use the agent-scoped+`POST /api/agents/{id}/qualify-runner` under the same `agent_config:update`+authorization as saving the upgrade. The server resolves the saved computer;+`expectedEnvironmentId` rejects stale state and cannot select another computer.+Qualification checks company binding, returns only its receipt, and audits within+the agent's company. General instance environment probes still require instance+admin. No probe runs merely on page load. Operator browser evidence does notqualify the agent permission paths for this operation.Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L1395) atdiff --git a/maps/feature-map/agents.md b/maps/feature-map/agents.mdindex 1d0f8edc0a..95fed092ec 100644--- a/maps/feature-map/agents.md+++ b/maps/feature-map/agents.md@@ -138,8 +138,10 @@ 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, or-probe-capable Daytona snapshots / immutable sandbox images, show **Upgrade runner** above their configuration. Exercise that action with-pending edits and an environment-variable draft; reopen the page and compare the+probe-capable Daytona snapshots / immutable sandbox images, show **Upgrade runner** above their configuration. Verify a company owner with `agents:configure` and no instance-admin role can qualify the saved computer and upgrade. A caller without configuration permission must be denied before a probe starts. Exercise that action with+pending edits and an environment-variable draft. An unsaved change to a different+effective computer must disable the action and explain that the computer change+must be saved first; restoring the saved target must re-enable it. Reopen the page and compare thesaved harness, model, account bindings, instructions, and run policy. Check asaved `maxTurnsPerRun: 1000`: upgrade must warn and remove it. Test an initiallyunqualified Daytona Paperclip Computer: click must probe, record qualification,diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex 5fd101bbb9..99f0a88550 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -1879,6 +1879,7 @@ export {wakeAgentSchema,resetAgentSessionSchema,testAdapterEnvironmentSchema,+ qualifyAgentRunnerSchema,agentPermissionsSchema,updateAgentPermissionsSchema,type CreateAgent,diff --git a/packages/shared/src/validators/agent.ts b/packages/shared/src/validators/agent.tsindex 80ad7076e6..32d65555e6 100644--- a/packages/shared/src/validators/agent.ts+++ b/packages/shared/src/validators/agent.ts@@ -180,6 +180,10 @@ export const updateAgentSchema = objectWithoutDefaults(export type UpdateAgent = z.infer<typeof updateAgentSchema>;+export const qualifyAgentRunnerSchema = z.object({+ expectedEnvironmentId: z.string().uuid(),+}).strict();+export const updateAgentInstructionsPathSchema = z.object({path: z.string().trim().min(1).nullable(),adapterConfigKey: z.string().trim().min(1).optional(),diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex b8fc304b7c..05519dd262 100644--- a/packages/shared/src/validators/index.ts+++ b/packages/shared/src/validators/index.ts@@ -367,6 +367,7 @@ export {wakeAgentSchema,resetAgentSessionSchema,testAdapterEnvironmentSchema,+ qualifyAgentRunnerSchema,agentPermissionsSchema,updateAgentPermissionsSchema,type CreateAgent,diff --git a/server/src/__tests__/agent-runner-qualification-routes.test.ts b/server/src/__tests__/agent-runner-qualification-routes.test.tsnew file mode 100644index 0000000000..3d50ad7d6a--- /dev/null+++ b/server/src/__tests__/agent-runner-qualification-routes.test.ts@@ -0,0 +1,123 @@+import { randomUUID } from "node:crypto";+import express from "express";+import request from "supertest";+import { eq } from "drizzle-orm";+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";+import { agents, authUsers, companies, companyMemberships, createDb, environments, principalPermissionGrants, activityLog, instanceSettings, builtInManagedResources, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS } from "@paperclipai/db";+import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";+import { grantsForHumanRole } from "../services/company-member-roles.js";+import { agentRoutes } from "../routes/agents.js";+import { environmentRoutes } from "../routes/environments.js";+import { errorHandler } from "../middleware/error-handler.js";++const probe = vi.hoisted(() => vi.fn());+vi.mock("../services/environment-probe.js", async original => ({+ ...await original<object>(), probeEnvironment: probe,+}));++const support = await getEmbeddedPostgresTestSupport();+describe.skipIf(!support.supported)("agent-scoped runner qualification", () => {+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;+ let db: ReturnType<typeof createDb>;+ let companyId: string;+ let agentId: string;+ let environmentId: string;+ let userId: string;+ let app: express.Express;++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("runner-qualification-");+ db = createDb(tempDb.connectionString);+ }, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS);+ afterAll(async () => { await tempDb?.cleanup(); });+ beforeEach(async () => {+ await db.delete(instanceSettings);+ await db.delete(environments);+ probe.mockReset().mockResolvedValue({ ok: true, driver: "sandbox", summary: "Connected",+ details: { platformQualificationRecorded: true, leaseId: "probe-lease", metadata: { private: "provider-secret" }, providerLeaseId: "private-id" } });+ companyId = randomUUID(); agentId = randomUUID(); environmentId = randomUUID(); userId = randomUUID();+ await db.insert(companies).values({ id: companyId, name: "Qualification", issuePrefix: `Q${companyId.slice(0, 7)}` });+ await db.insert(authUsers).values({ id: userId, name: "Company owner", email: `${userId}@example.test`, emailVerified: true, createdAt: new Date(), updatedAt: new Date() });+ await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: userId, membershipRole: "owner", status: "active" });+ await db.insert(principalPermissionGrants).values(grantsForHumanRole("owner").map(grant => ({ ...grant, companyId, principalType: "user" as const, principalId: userId })));+ await db.insert(environments).values({ id: environmentId, name: `Paperclip Computer ${environmentId}`, driver: "sandbox", status: "active", config: { provider: "daytona", snapshot: "managed-snapshot" } });+ await db.insert(agents).values({ id: agentId, companyId, name: "Amy fixture", adapterType: "claude_local", defaultEnvironmentId: environmentId,+ adapterConfig: { model: "claude-opus-5-5", effort: "high", maxTurnsPerRun: 1000, dangerouslySkipPermissions: true } });+ app = express(); app.use(express.json());+ app.use((req, _res, next) => {+ req.actor = { type: "board", userId, companyIds: [companyId], source: "cloud_tenant", isInstanceAdmin: false,+ memberships: [{ companyId, membershipRole: "owner", status: "active" }] };+ next();+ });+ app.use("/api", agentRoutes(db));+ app.use("/api", environmentRoutes(db));+ app.use(errorHandler);+ });+ const qualify = () => request(app).post(`/api/agents/${agentId}/qualify-runner`).send({ expectedEnvironmentId: environmentId });++ it("allows the company owner without instance admin and keeps the generic probe restricted", async () => {+ const before = await db.select().from(agents).where(eq(agents.id, agentId));+ const res = await qualify();+ expect(res.status).toBe(200);+ expect(res.body).toMatchObject({ ok: true, details: { platformQualificationRecorded: true, leaseId: "probe-lease" } });+ expect(JSON.stringify(res.body)).not.toMatch(/provider-secret|private-id/);+ expect(probe).toHaveBeenCalledWith(db, expect.objectContaining({ id: environmentId }), expect.objectContaining({ companyId, assertCompanyBinding: true, acquireSandboxRuntimeLease: true, applyCustomImageTemplate: true }));+ expect(await db.select().from(agents).where(eq(agents.id, agentId))).toEqual(before);+ const audit = await db.select().from(activityLog).where(eq(activityLog.entityId, agentId));+ expect(audit).toEqual([expect.objectContaining({ companyId, actorId: userId, action: "agent.runner_qualification_tested" })]);+ const generic = await request(app).post(`/api/environments/${environmentId}/probe?companyId=${companyId}`).send({});+ expect(generic.status).toBe(403);+ expect(probe).toHaveBeenCalledTimes(1);+ });+ it("rejects an owner whose configure grant is absent before any provider work", async () => {+ await db.delete(principalPermissionGrants).where(eq(principalPermissionGrants.principalId, userId));+ expect((await qualify()).status).toBe(403);+ expect(probe).not.toHaveBeenCalled();+ });+ it("hides a foreign agent before any provider work", async () => {+ const other = randomUUID();+ await db.insert(companies).values({ id: other, name: "Other", issuePrefix: `F${other.slice(0, 7)}` });+ await db.update(agents).set({ companyId: other }).where(eq(agents.id, agentId));+ expect((await qualify()).status).toBe(404);+ expect(probe).not.toHaveBeenCalled();+ });+ it("treats the submitted environment as a stale-state check, not a target override", async () => {+ const res = await request(app).post(`/api/agents/${agentId}/qualify-runner`).send({ expectedEnvironmentId: randomUUID() });+ expect(res.status).toBe(409);+ expect(probe).not.toHaveBeenCalled();+ });+ it("rejects a managed computer bound to a different company", async () => {+ const other = randomUUID();+ await db.insert(companies).values({ id: other, name: "Other", issuePrefix: `F${other.slice(0, 7)}` });+ await db.insert(builtInManagedResources).values({ companyId: other, bundleKey: "test", resourceKind: "environment", resourceKey: "computer", resourceId: environmentId, stockVersion: "test", stockHash: "test" });+ expect((await qualify()).status).toBe(403);+ expect(probe).not.toHaveBeenCalled();+ });+ it.each(["instance", "managed", "kubernetes"])("resolves the %s computer with the same policy as runner saving", async mode => {+ await db.update(agents).set({ defaultEnvironmentId: null }).where(eq(agents.id, agentId));+ await db.update(environments).set({ metadata: { managedByPaperclip: true, managedKubernetesSandbox: mode === "kubernetes" },+ ...(mode === "kubernetes" ? { config: { provider: "kubernetes" } } : {}) }).where(eq(environments.id, environmentId));+ await db.insert(instanceSettings).values({ defaultEnvironmentId: mode === "instance" ? environmentId : null,+ experimental: { enableManagedSandboxOnly: mode === "managed" }, general: { executionMode: mode === "kubernetes" ? "kubernetes" : "local" } });+ expect((await qualify()).status).toBe(200);+ expect(probe).toHaveBeenCalledWith(db, expect.objectContaining({ id: environmentId }), expect.anything());+ });+ it("does not accept arbitrary provider config or a target override", async () => {+ const res = await request(app).post(`/api/agents/${agentId}/qualify-runner`).send({ expectedEnvironmentId: environmentId, config: { image: "untrusted" } });+ expect(res.status).toBe(400);+ expect(probe).not.toHaveBeenCalled();+ });+ it.each(["archived", "local"])("rejects an ineligible %s environment", async state => {+ await db.update(environments).set(state === "archived" ? { status: "archived" } : { driver: "local", config: {} }).where(eq(environments.id, environmentId));+ expect((await qualify()).status).toBe(422);+ expect(probe).not.toHaveBeenCalled();+ });+ it("returns a failed qualification without exposing provider diagnostics or changing the agent", async () => {+ probe.mockResolvedValue({ ok: false, driver: "sandbox", summary: "provider-secret", details: { error: "provider-secret" } });+ const res = await qualify();+ expect(res.status).toBe(200);+ expect(res.body.ok).toBe(false);+ expect(JSON.stringify(res.body)).not.toContain("provider-secret");+ expect((await db.select().from(agents).where(eq(agents.id, agentId)))[0]?.adapterType).toBe("claude_local");+ });+});diff --git a/server/src/__tests__/environment-probe.test.ts b/server/src/__tests__/environment-probe.test.tsindex 94d334fdda..e00c2d3eb6 100644--- a/server/src/__tests__/environment-probe.test.ts+++ b/server/src/__tests__/environment-probe.test.ts@@ -56,9 +56,9 @@ describe("probeEnvironment", () => {vi.spyOn(configRuntime, "resolveEnvironmentDriverConfigForRuntime").mockResolvedValue({ driver: "sandbox", config: environment.config });mockRuntimeAcquireRunLease.mockResolvedValue({ lease: { id: "lease", provider: "daytona", metadata: { snapshot: "managed-snapshot", snapshotIdentity: identity } } });mockRuntimeExecute.mockResolvedValue({ exitCode: 0, stdout: "Linux\nx86_64\nglibc\nglibc 2.39\n" });- const result = await probeEnvironment({} as any, environment, { companyId: "company", acquireSandboxRuntimeLease: true });+ const result = await probeEnvironment({} as any, environment, { companyId: "company", acquireSandboxRuntimeLease: true, assertCompanyBinding: true });expect(result.details?.platformQualificationRecorded).toBe(true);- expect(mockRuntimeAcquireRunLease).toHaveBeenCalledWith(expect.objectContaining({ resolveSnapshotIdentity: true }));+ expect(mockRuntimeAcquireRunLease).toHaveBeenCalledWith(expect.objectContaining({ resolveSnapshotIdentity: true, assertCompanyBinding: true }));const proof = mockRecordPlatformProbe.mock.calls[1]![0].proof;expect(proof).toMatchObject({ v: 2, snapshotIdentity: identity });environment.metadata = { [SANDBOX_PLATFORM_PROBE_METADATA_KEY]: { company: proof } };diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex 0a03946e7f..540e1f7d8c 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -4,6 +4,7 @@ import { cancellationRequestId } from "../services/native-runtime/native-cancellimport { agentHarnessType, isEnvironmentDriverSupportedForAdapter, normalizeClaudeRunnerOptions, type AgentConfigurationWarning, type AgentRunnerChoice } from "@paperclipai/shared";import { resolveNewAgentRunnerForCompany } from "../services/agent-runner-selection.js";import { agentEnvironmentTestService } from "../services/agent-environment-test.js";+import { qualifyAgentRunner } from "../services/agent-runner-qualification.js";import { createAgentLifecycle } from "../services/agent-lifecycle.js";import { agentIdentityService } from "../services/agent-identity.js";@@ -65,6 +66,7 @@ import {normalizeIssueIdentifier,resetAgentSessionSchema,testAdapterEnvironmentSchema,+ qualifyAgentRunnerSchema,type AgentDesiredSkillEntry,type AgentSkillAssignmentMode,type AgentSkillSnapshot,@@ -1800,6 +1802,25 @@ export function agentRoutes(await assertCanUpdateAgent(req, targetAgent);}+ router.post("/agents/:id/qualify-runner", validate(qualifyAgentRunnerSchema), async (req, res) => {+ const agent = await getAccessibleResource(req, res, svc.getById(req.params.id as string), "Agent not found");+ if (!agent) return;+ await assertCanUpdateAgent(req, agent);+ const result = await qualifyAgentRunner(db, agent, req.body.expectedEnvironmentId, options.pluginWorkerManager);+ const actor = getActorInfo(req);+ await logActivity(db, {+ companyId: agent.companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ action: "agent.runner_qualification_tested",+ entityType: "agent",+ entityId: agent.id,+ details: { environmentId: req.body.expectedEnvironmentId, ok: result.ok,+ platformQualificationRecorded: result.details?.platformQualificationRecorded === true },+ });+ res.json(result);+ });+async function assertCanReadAgent(req: Request, targetAgent: { id: string; companyId: string }) {if (!hasCompanyAccess(req, targetAgent.companyId)) {throw notFound("Agent not found");diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.tsindex 45fb61d344..650eb0670e 100644--- a/server/src/routes/openapi.ts+++ b/server/src/routes/openapi.ts@@ -67,6 +67,7 @@ import {resetAgentSessionSchema,agentSkillSyncSchema,testAdapterEnvironmentSchema,+ qualifyAgentRunnerSchema,// IssuecreateIssueSchema,setIssueTitleSchema,@@ -4130,6 +4131,16 @@ registry.registerPath({responses: { 200: r.ok(), 400: r.badRequest, 401: r.unauthorized },});+registry.registerPath({+ method: "post",+ path: "/api/agents/{id}/qualify-runner",+ tags: ["agents"],+ summary: "Qualify an existing agent's saved computer for a runner upgrade",+ description: "Requires agent_config:update authorization, normally agents:configure. Resolves the saved agent's effective sandbox; expectedEnvironmentId only guards against stale UI state. Does not change the agent or grant instance environment access.",+ request: { params: z.object({ id: z.string() }), body: jsonBody(qualifyAgentRunnerSchema) },+ responses: { 200: r.ok(), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden, 404: r.notFound, 409: r.conflict, 422: r.unprocessable },+});+registry.registerPath({method: "get",path: "/api/companies/{companyId}/adapters/{type}/auth-signal",diff --git a/server/src/services/agent-runner-qualification.ts b/server/src/services/agent-runner-qualification.tsnew file mode 100644index 0000000000..f6b73618e2--- /dev/null+++ b/server/src/services/agent-runner-qualification.ts@@ -0,0 +1,42 @@+import type { Db } from "@paperclipai/db";+import type { Agent, EnvironmentProbeResult } from "@paperclipai/shared";+import { conflict, unprocessable } from "../errors.js";+import { resolveAgentRunnerEnvironmentForCompany } from "./agent-runner-selection.js";+import { probeEnvironment } from "./environment-probe.js";+import type { PluginWorkerManager } from "./plugin-worker-manager.js";++export async function qualifyAgentRunner(+ db: Db,+ agent: Pick<Agent, "companyId" | "adapterType" | "defaultEnvironmentId">,+ expectedEnvironmentId: string,+ pluginWorkerManager?: PluginWorkerManager,+): Promise<EnvironmentProbeResult> {+ if (!["claude_local", "codex_local"].includes(agent.adapterType)) {+ throw unprocessable("This agent does not need a runner upgrade.");+ }+ const { environment } = await resolveAgentRunnerEnvironmentForCompany(db, agent.companyId, agent.defaultEnvironmentId);+ if (!environment || environment.id !== expectedEnvironmentId) {+ throw conflict("The agent's computer changed. Save any environment changes, reload, and retry the upgrade.");+ }+ if (environment.driver !== "sandbox") {+ throw unprocessable("This computer does not need sandbox qualification.");+ }+ const result = await probeEnvironment(db, environment, {+ companyId: agent.companyId,+ pluginWorkerManager,+ applyCustomImageTemplate: true,+ acquireSandboxRuntimeLease: true,+ assertCompanyBinding: true,+ });+ const qualified = result.ok === true && result.details?.platformQualificationRecorded === true;+ return {+ ok: result.ok,+ driver: "sandbox",+ summary: qualified ? "The agent's computer is qualified for runner selection."+ : "Could not qualify the agent's computer. Retry the upgrade or keep Legacy runner.",+ details: {+ platformQualificationRecorded: qualified,+ ...(typeof result.details?.leaseId === "string" ? { leaseId: result.details.leaseId } : {}),+ },+ };+}diff --git a/server/src/services/agent-runner-selection.ts b/server/src/services/agent-runner-selection.tsindex 42347ccad2..7d87a5b9d8 100644--- a/server/src/services/agent-runner-selection.ts+++ b/server/src/services/agent-runner-selection.ts@@ -290,6 +290,28 @@ export async function resolveNewAgentRunnerForCompany(db: Db, companyId: string,export async function resolveAgentRunnerTargetForCompany(db: Db, companyId: string, defaultEnvironmentId?: string | null): Promise<RunnerTarget> {await waitForExternalAdapters();+ const { environment, driver } = await resolveAgentRunnerEnvironmentForCompany(db, companyId, defaultEnvironmentId);+ let target: RunnerTarget = driver === "local" ? localAgentRunnerTarget()+ : { driver };+ if (driver === "plugin" && environment && await pluginEnvironmentRunsRunnerTasks(db, environment)) target = { driver, runnerTasks: true };+ if (driver === "sandbox" && environment) {+ const { readSandboxPlatformQualification } = await import("./environment-probe.js");+ const qualified = await readSandboxPlatformQualification(db, environment, companyId);+ if (qualified) target = { driver, ...qualified };+ }+ if (driver === "ssh" && environment && ["codex_local", "claude_local", "opencode_local", "pi_local"].some(harness => runnerAdaptersAvailable(harness, driver))) {+ const parsed = await resolveEnvironmentDriverConfigForRuntime(db, companyId, environment);+ if (parsed.driver !== "ssh") throw unprocessable("The selected SSH environment is unavailable.");+ let output: string;+ try { output = (await runSshCommand(parsed.config, AGENT_RUNNER_SSH_PLATFORM_COMMAND, { timeoutMs: 10_000 })).stdout; }+ catch { throw unprocessable("Could not check the SSH host's platform. Check its connection and retry, or select Legacy runner in Advanced.", { code: "agent_runner_platform_probe_failed" }); }+ const [os = "", arch = "", libc, glibcVersion] = output.trim().split(/\r?\n/);+ target = { driver, platform: os === "Linux" ? "linux" : os === "Darwin" ? "darwin" : "unknown", architecture: arch === "x86_64" ? "x64" : ["aarch64", "arm64"].includes(arch) ? "arm64" : arch, ...(os === "Linux" && libc !== undefined ? { libc: libc === "glibc" || libc === "musl" ? libc : "unknown", ...(libc === "glibc" && glibcVersion !== undefined ? { glibcVersion } : {}) } : {}) };+ }+ return target;+}++export async function resolveAgentRunnerEnvironmentForCompany(db: Db, companyId: string, defaultEnvironmentId?: string | null) {const { instanceSettingsService } = await import("./instance-settings.js");const { environmentService } = await import("./environments.js");const settings = await instanceSettingsService(db).get();@@ -302,7 +324,7 @@ export async function resolveAgentRunnerTargetForCompany(db: Db, companyId: stri}if (settings.general?.executionMode === "kubernetes") {environment = await envs.findKubernetesEnvironment(companyId);- if (!environment) return { driver: "sandbox" };+ if (!environment) return { environment: null, driver: "sandbox" };}if (environmentId && !environment) throw unprocessable("Environment not found.");if (environment) {@@ -311,25 +333,7 @@ export async function resolveAgentRunnerTargetForCompany(db: Db, companyId: striif (environment.status === "archived") throw unprocessable("Environment is archived.");if (environment.driver === "sandbox" && environment.config?.provider === "fake") throw unprocessable("The fake sandbox provider cannot execute runs.");}- const driver = environment?.driver ?? "local";- let target: RunnerTarget = driver === "local" ? localAgentRunnerTarget()- : { driver };- if (driver === "plugin" && environment && await pluginEnvironmentRunsRunnerTasks(db, environment)) target = { driver, runnerTasks: true };- if (driver === "sandbox" && environment) {- const { readSandboxPlatformQualification } = await import("./environment-probe.js");- const qualified = await readSandboxPlatformQualification(db, environment, companyId);- if (qualified) target = { driver, ...qualified };- }- if (driver === "ssh" && environment && ["codex_local", "claude_local", "opencode_local", "pi_local"].some(harness => runnerAdaptersAvailable(harness, driver))) {- const parsed = await resolveEnvironmentDriverConfigForRuntime(db, companyId, environment);- if (parsed.driver !== "ssh") throw unprocessable("The selected SSH environment is unavailable.");- let output: string;- try { output = (await runSshCommand(parsed.config, AGENT_RUNNER_SSH_PLATFORM_COMMAND, { timeoutMs: 10_000 })).stdout; }- catch { throw unprocessable("Could not check the SSH host's platform. Check its connection and retry, or select Legacy runner in Advanced.", { code: "agent_runner_platform_probe_failed" }); }- const [os = "", arch = "", libc, glibcVersion] = output.trim().split(/\r?\n/);- target = { driver, platform: os === "Linux" ? "linux" : os === "Darwin" ? "darwin" : "unknown", architecture: arch === "x86_64" ? "x64" : ["aarch64", "arm64"].includes(arch) ? "arm64" : arch, ...(os === "Linux" && libc !== undefined ? { libc: libc === "glibc" || libc === "musl" ? libc : "unknown", ...(libc === "glibc" && glibcVersion !== undefined ? { glibcVersion } : {}) } : {}) };- }- return target;+ return { environment, driver: environment?.driver ?? "local" };}// The plugin's manifest declaration decides whether its environment runsdiff --git a/server/src/services/environment-probe.ts b/server/src/services/environment-probe.tsindex c743e0f295..7f15b03656 100644--- a/server/src/services/environment-probe.ts+++ b/server/src/services/environment-probe.ts@@ -76,6 +76,7 @@ export async function probeEnvironment(resolvedConfig?: ParsedEnvironmentConfig;applyCustomImageTemplate?: boolean;acquireSandboxRuntimeLease?: boolean;+ assertCompanyBinding?: boolean;} = {},): Promise<EnvironmentProbeResult> {const resolvedCompanyId = options.companyId ?? null;@@ -148,6 +149,7 @@ export async function probeEnvironment(persistedExecutionWorkspace: null,adapterType: null,resolveSnapshotIdentity: true,+ assertCompanyBinding: options.assertCompanyBinding,applyCustomImageTemplate: options.applyCustomImageTemplate === true,});const metadata = leaseRecord.lease.metadata ?? {};diff --git a/ui/src/api/agents.ts b/ui/src/api/agents.tsindex b1d0e32587..5d31460ea3 100644--- a/ui/src/api/agents.ts+++ b/ui/src/api/agents.ts@@ -1,6 +1,7 @@import type { AgentPublicIdentity } from "@paperclipai/shared";import type {Agent,+ EnvironmentProbeResult,ConnectionIntentInteraction,AgentDesiredSkillEntry,AgentSkillAssignmentMode,@@ -110,6 +111,8 @@ function agentPath(id: string, companyId?: string, suffix = "") {}export const agentsApi = {+ qualifyRunner: (id: string, expectedEnvironmentId: string, companyId?: string) =>+ api.post<EnvironmentProbeResult>(agentPath(id, companyId, "/qualify-runner"), { expectedEnvironmentId }),setAvatar: (companyId: string, agentId: string, imageBase64: string | null) =>api.put<{ agentId: string; appearance: import("@paperclipai/shared").AgentAppearance; avatarUrl: string }>(`/companies/${companyId}/agents/${agentId}/avatar`, { imageBase64 }),getIdentity: (id: string, companyId?: string) =>diff --git a/ui/src/components/AgentConfigForm.render.test.tsx b/ui/src/components/AgentConfigForm.render.test.tsxindex 244d13e83d..9ecfc4a9c8 100644--- a/ui/src/components/AgentConfigForm.render.test.tsx+++ b/ui/src/components/AgentConfigForm.render.test.tsx@@ -27,6 +27,7 @@ const mockAgentsApi = vi.hoisted(() => ({detectModel: vi.fn(),list: vi.fn(),testEnvironment: vi.fn(),+ qualifyRunner: vi.fn(),startAdapterAuthLogin: vi.fn(),getAdapterAuthLoginStatus: vi.fn(),getActiveAdapterAuthLoginSession: vi.fn(),@@ -817,7 +818,7 @@ describe("AgentConfigForm environment selector", () => {{ type: "paperclip_runner", supportedRunners: ["legacy"], defaultRunner: "legacy" },];mockAdaptersApi.list.mockResolvedValue(inventory(false));- mockEnvironmentsApi.probe.mockImplementation(async () => {+ mockAgentsApi.qualifyRunner.mockImplementation(async () => {mockAdaptersApi.list.mockResolvedValue(inventory(true));return { ok: true, driver: "sandbox", details: { platformQualificationRecorded: true, leaseId: "probe-lease" } };});@@ -829,7 +830,7 @@ describe("AgentConfigForm environment selector", () => {roots.push(result.root);expect(result.container.textContent).toContain("Upgrade to Paperclip Runner");expect(result.container.textContent).toContain("Max turns per run");- expect(mockEnvironmentsApi.probe).not.toHaveBeenCalled();+ expect(mockAgentsApi.qualifyRunner).not.toHaveBeenCalled();if (mode === "env-draft") {await clickByText(result.container, "Add variable");await act(async () => {@@ -839,19 +840,40 @@ describe("AgentConfigForm environment selector", () => {await flushReact();}await clickByText(result.container, "Upgrade runner");- expect(mockEnvironmentsApi.probe).toHaveBeenCalledWith(environment.id, "company-1");+ expect(mockAgentsApi.qualifyRunner).toHaveBeenCalledWith("agent-1", environment.id, "company-1");expect(result.onSave).toHaveBeenCalledWith(mode === "env-draft" ? expect.objectContaining({runner: "paperclip", replaceAdapterConfig: true,adapterConfig: expect.objectContaining({ env: { MIGRATION_MARKER: { type: "plain", value: "kept" } } }),}) : { runner: "paperclip" });});+ it.each([false, true])("requires saving a changed computer before upgrading (qualified: %s)", async qualified => {+ const environments = ["saved-computer", "draft-computer"].map(id => makeEnvironment({ id, driver: "sandbox", status: "active",+ config: { provider: "daytona", snapshot: "managed-snapshot" } }));+ mockAdaptersApi.list.mockResolvedValue([+ { type: "claude_local", supportedRunners: qualified ? ["paperclip", "legacy"] : ["legacy"], defaultRunner: qualified ? "paperclip" : "legacy" },+ { type: "paperclip_runner", supportedRunners: ["legacy"], defaultRunner: "legacy" },+ ]);+ const result = await renderForm(environments, { adapterType: "claude_local", defaultEnvironmentId: "saved-computer" });+ roots.push(result.root);+ expect(findButton(result.container, "Upgrade runner")?.disabled).toBe(false);+ await selectEnvironment(result.container, "draft-computer");+ expect(findButton(result.container, "Upgrade runner")?.disabled).toBe(true);+ expect(result.container.textContent).toContain("Save your computer change before upgrading the runner.");+ await clickByText(result.container, "Upgrade runner");+ expect(mockAgentsApi.qualifyRunner).not.toHaveBeenCalled();+ expect(result.onSave).not.toHaveBeenCalled();+ await selectEnvironment(result.container, "saved-computer");+ expect(findButton(result.container, "Upgrade runner")?.disabled).toBe(false);+ expect(result.container.textContent).not.toContain("Save your computer change before upgrading the runner.");+ });+it.each(["probe", "unsupported", "settings-changed"])("does not save after Daytona %s", async failure => {const environment = makeEnvironment({ id: "daytona-computer", name: "Paperclip Computer", driver: "sandbox", status: "active",config: { provider: "daytona", snapshot: "managed-snapshot" } });mockAdaptersApi.list.mockResolvedValue([{ type: "claude_local", supportedRunners: ["legacy"], defaultRunner: "legacy" }, { type: "paperclip_runner", supportedRunners: ["legacy"], defaultRunner: "legacy" }]);let finish!: () => void;- mockEnvironmentsApi.probe.mockImplementation(() => new Promise(resolve => { finish = () => resolve({ ok: failure !== "probe",+ mockAgentsApi.qualifyRunner.mockImplementation(() => new Promise(resolve => { finish = () => resolve({ ok: failure !== "probe",summary: "Could not verify this computer", details: { platformQualificationRecorded: failure !== "probe", leaseId: "lease" } }); }));const result = await renderForm([environment], { adapterType: "claude_local", defaultEnvironmentId: environment.id });roots.push(result.root);@@ -874,7 +896,7 @@ describe("AgentConfigForm environment selector", () => {{ type: "paperclip_runner", supportedRunners: ["legacy"], defaultRunner: "legacy" },];mockAdaptersApi.list.mockResolvedValue(inventory(false));- mockEnvironmentsApi.probe.mockImplementation(async () => {+ mockAgentsApi.qualifyRunner.mockImplementation(async () => {mockAdaptersApi.list.mockResolvedValue(inventory(true));return { ok: true, details: { platformQualificationRecorded: true, leaseId: "kubernetes-probe" } };});@@ -884,12 +906,12 @@ describe("AgentConfigForm environment selector", () => {roots.push(result.root);if (available) {await clickByText(result.container, "Upgrade runner");- expect(mockEnvironmentsApi.probe).toHaveBeenCalledWith(kubernetes.id, "company-1");+ expect(mockAgentsApi.qualifyRunner).toHaveBeenCalledWith("agent-1", kubernetes.id, "company-1");expect(mockAdaptersApi.list).toHaveBeenLastCalledWith({ companyId: "company-1", environmentId: kubernetes.id });expect(result.onSave).toHaveBeenCalledWith({ runner: "paperclip" });} else {expect(findButton(result.container, "Upgrade runner")).toBeUndefined();- expect(mockEnvironmentsApi.probe).not.toHaveBeenCalled();+ expect(mockAgentsApi.qualifyRunner).not.toHaveBeenCalled();}});@@ -1023,6 +1045,7 @@ describe("AgentConfigForm environment selector", () => {beforeEach(() => {mockEnvironmentsApi.probe.mockReset();+ mockAgentsApi.qualifyRunner.mockReset();mockAdaptersApi.list.mockReset().mockResolvedValue([{ type: "codex_local", supportedRunners: ["legacy", "paperclip"], defaultRunner: "legacy" }]);mockAgentsApi.adapterModels.mockResolvedValue([]);mockAgentsApi.detectModel.mockResolvedValue(null);diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsxindex c8e2ceb60c..fb5a0fc7ab 100644--- a/ui/src/components/AgentConfigForm.tsx+++ b/ui/src/components/AgentConfigForm.tsx@@ -867,25 +867,33 @@ export function AgentConfigForm(props: AgentConfigFormProps) {// is on but no managed sandbox is available; a render must not throw, so this// resolution catches that case and resolves no login environment. The Test// mutation surfaces the same case as a fail-closed error.- const effectiveLoginEnvironmentId = useMemo(() => {- try {- return resolveAdapterTestEnvironmentId({- agentDefaultEnvironmentId: rawCurrentDefaultEnvironmentId || null,- instanceDefaultEnvironmentId: instanceSettings?.defaultEnvironmentId ?? null,- localDefaultEnvironmentId: resolveLocalDefaultEnvironmentId(environments),- managedSandboxOnly: experimentalSettings?.enableManagedSandboxOnly === true,- managedSandboxEnvironmentId: resolveManagedSandboxEnvironmentId(environments),- // The policy hides the local environment, so an agent default that still- // points at the hidden local row names no visible environment. Pass the- // visible ids so the resolver redirects that stale local default to the- // managed sandbox instead of the hidden local id.- visibleEnvironmentIds: environments.map((environment) => environment.id),- });- } catch {- return null;- }+ const savedDefaultEnvironmentId = isCreate ? null : props.agent.defaultEnvironmentId ?? null;+ const { effectiveLoginEnvironmentId, savedLoginEnvironmentId } = useMemo(() => {+ const resolve = (agentDefaultEnvironmentId: string | null) => {+ try {+ return resolveAdapterTestEnvironmentId({+ agentDefaultEnvironmentId,+ instanceDefaultEnvironmentId: instanceSettings?.defaultEnvironmentId ?? null,+ localDefaultEnvironmentId: resolveLocalDefaultEnvironmentId(environments),+ managedSandboxOnly: experimentalSettings?.enableManagedSandboxOnly === true,+ managedSandboxEnvironmentId: resolveManagedSandboxEnvironmentId(environments),+ // The policy hides the local environment, so an agent default that still+ // points at the hidden local row names no visible environment. Pass the+ // visible ids so the resolver redirects that stale local default to the+ // managed sandbox instead of the hidden local id.+ visibleEnvironmentIds: environments.map((environment) => environment.id),+ });+ } catch {+ return null;+ }+ };+ return {+ effectiveLoginEnvironmentId: resolve(rawCurrentDefaultEnvironmentId || null),+ savedLoginEnvironmentId: resolve(savedDefaultEnvironmentId),+ };}, [rawCurrentDefaultEnvironmentId,+ savedDefaultEnvironmentId,instanceSettings?.defaultEnvironmentId,environments,experimentalSettings?.enableManagedSandboxOnly,@@ -897,6 +905,8 @@ export function AgentConfigForm(props: AgentConfigFormProps) {const nativeRunnerAvailability = runnerDiscovery.data?.find(item => item.type === "paperclip_runner");const upgradeEnvironment = forcedKubernetes ? kubernetesEnvironment : effectiveLoginEnvironment;const upgradeEnvironmentId = upgradeEnvironment?.id ?? null;+ const upgradeEnvironmentChanged = !isCreate && !forcedKubernetes+ && effectiveLoginEnvironmentId !== savedLoginEnvironmentId;const canQualifyRunnerUpgrade = upgradeEnvironment?.status === "active"&& canQualifyRunnerEnvironment(upgradeEnvironment)&& Boolean(runnerAvailability && !runnerAvailability.disabled && !runnerAvailability.overriddenBuiltin)@@ -913,7 +923,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {&& !runnerDiscovery.isError&& (runnerAvailability?.defaultRunner === "paperclip" || canQualifyRunnerUpgrade);const upgradeRunner = async () => {- if (isCreate || runnerUpgradePending) return;+ if (isCreate || runnerUpgradePending || upgradeEnvironmentChanged) return;const agentId = props.agent.id;setRunnerUpgrade({ agentId, status: "pending" });try {@@ -929,7 +939,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {const qualified = await qualifyRunnerEnvironment({adapterType: harnessType,readAdapters: () => adaptersApi.list({ companyId: selectedCompanyId, environmentId: upgradeEnvironmentId }),- probeEnvironment: () => environmentsApi.probe(upgradeEnvironmentId, selectedCompanyId),+ probeEnvironment: () => agentsApi.qualifyRunner(agentId, upgradeEnvironmentId, selectedCompanyId),isCurrent: () => upgradeTargetRef.current === pendingTarget,});if (!qualified) throw new Error("Agent settings changed during verification. Retry the upgrade with the current settings.");@@ -1578,9 +1588,11 @@ export function AgentConfigForm(props: AgentConfigFormProps) {<p className="text-xs text-muted-foreground">The upgrade will verify your computer first. This can take a few minutes.</p>) : null}{upgradeWarnings.map(warning => <p key={warning.field} className="text-xs text-muted-foreground">{warning.message}</p>)}- {isDirty ? <p className="text-xs text-muted-foreground">Your unsaved changes will be included.</p> : null}+ {upgradeEnvironmentChanged ? (+ <p className="text-xs text-muted-foreground">Save your computer change before upgrading the runner.</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)}>+ <Button size="sm" className="self-end sm:self-auto" onClick={upgradeRunner} disabled={runnerUpgradePending || upgradeEnvironmentChanged || (!isCreate && props.isSaving)}>{runnerUpgradePending ? <Loader2 className="size-4 animate-spin" /> : null}{runnerUpgradePending ? "Upgrading…" : "Upgrade runner"}</Button>