From 782d6bead4e5ba60e8dc880b2cb0c9406dd0d901 Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Thu, 12 Nov 2026 08:18:04 -0800 Subject: [PATCH] Configure managed plugin Runner lifecycle (#21065) ## Thinking Path > - Paperclip runs agents in managed environments. > - An agent can use an explicit environment or the instance default. > - A lifecycle plugin must receive the driver that provisions the agent. > - A managed plugin environment also needs to select the Runner process lifecycle. > - This change gives lifecycle selection and provisioning the same environment lookup. ## Linked Issues or Issue Description **What existing behavior does this improve?** Managed plugin environment provisioning and lifecycle configuration. **Current behavior** Lifecycle calls lack the selected plugin driver. Managed plugin configuration cannot select warm Runner execution. **Proposed behavior** Resolve the environment once per lifecycle operation. Pass the driver key for the plugin that serves it. Parse and persist the managed Runner lifecycle mode. The portable ownership and workspace placement changes are in [#21066](https://github.com/paperclipai/paperclip/pull/21066) and [#20743](https://github.com/paperclipai/paperclip/pull/20743). ## What Changed - Share agent environment resolution between required plugin selection and the lifecycle RPC. - Pass `environmentDriverKey` to the plugin that serves the selected environment. - Allow managed plugin environments to set `warm` or `per_turn` and persist the selected mode. - Advertise `pluginEnvironmentRunnerLifecycleMode` in the release capability manifest so senders can check support before including the field. ## Verification - Built shared types, the plugin SDK, and Runner. Server typecheck and SDK source-pin check passed for the initial layer. - The capability contract test failed before the manifest fix and passed after it. Independent verification passed all 160 tests across managed configuration, plugin environment persistence, lifecycle routing, and environment reconciliation. - Routing coverage includes the instance default, an explicit second driver from the same plugin, and an explicit sandbox. - [Hosted CI](https://github.com/paperclipai/paperclip/actions/runs/43193311862) passed on `f07b192c21`. The first attempt timed out in an unchanged workspace-recovery fixture and then collided with a background recovery action. The exact test and all 44 tests in its suite passed locally; the isolated shard retry passed without code changes. ## Risks - Existing managed configuration can omit the lifecycle mode. Senders must check the target release for `pluginEnvironmentRunnerLifecycleMode` before sending the new field. Publishing this signal does not update external deployment tools. ## Model Used - OpenAI Codex GPT-6 with GPT-6.1 Sol agents for implementation and independent review. ## Checklist - [x] Thinking path and model are included. - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] The issue is described using the enhancement template. - [x] Local checks passed and new behavior has tests. - [x] All Paperclip CI gates are green. - [x] Greptile is 5/5 with no open findings. --------- Co-authored-by: Paperclip --- doc/DEVELOPING.md | 4 +- packages/shared/src/types/agent-lifecycle.ts | 1 + server/src/__tests__/managed-config.test.ts | 10 +++++ .../managed-plugin-environments.test.ts | 40 +++++++++++++++---- server/src/services/agent-lifecycle-driver.ts | 18 +++++++-- .../services/managed-config-capabilities.json | 2 +- .../managed-config-capabilities.test.ts | 2 +- server/src/services/managed-config.ts | 12 +++++- server/src/services/managed-environments.ts | 1 + .../services/managed-plugin-environments.ts | 4 +- .../runner-e2e/source-sdk-public-inputs.json | 2 +- 11 files changed, 78 insertions(+), 18 deletions(-) diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index bcd6a197f55..dcd4af6039b 100644 --- a/doc/DEVELOPING.md +++ b/doc/DEVELOPING.md @@ -2183,7 +2183,9 @@ admin can change it in instance settings. capabilities a release supports, for the control plane to read at a release commit. It must equal `MANAGED_CONFIG_CAPABILITIES` in `managed-config.ts` (`managed-config-capabilities.test.ts` checks this), and the parser accepts plugin -entries only while that list includes `pluginEnvironments`. +entries only while that list includes `pluginEnvironments`. When sending a plugin +environment, include `runnerLifecycleMode` only if the target release also lists +`pluginEnvironmentRunnerLifecycleMode`. ### Experimental native remote workspace storage diff --git a/packages/shared/src/types/agent-lifecycle.ts b/packages/shared/src/types/agent-lifecycle.ts index 3ff9d17a2b7..dcc5105d578 100644 --- a/packages/shared/src/types/agent-lifecycle.ts +++ b/packages/shared/src/types/agent-lifecycle.ts @@ -36,6 +36,7 @@ export interface AgentLifecycleRequest { operationId: string; version: number; phase: AgentLifecycleState; + environmentDriverKey?: string; instanceSecrets?: Record; } export interface AgentLifecycleResult { diff --git a/server/src/__tests__/managed-config.test.ts b/server/src/__tests__/managed-config.test.ts index c8229ed578e..2927f30ba7f 100644 --- a/server/src/__tests__/managed-config.test.ts +++ b/server/src/__tests__/managed-config.test.ts @@ -470,6 +470,16 @@ describe("parseManagedConfigEnv plugin environment entries", () => { expect(config?.pluginEnvironments[0]?.description).toBeUndefined(); }); + it.each(["warm", "per_turn"])("parses the %s plugin Runner lifecycle mode", runnerLifecycleMode => { + const config = parseManagedConfigEnv(docWith([remoteHost({ runnerLifecycleMode })])); + expect(config?.pluginEnvironments[0]?.runnerLifecycleMode).toBe(runnerLifecycleMode); + }); + + it("rejects an unsupported plugin Runner lifecycle mode", () => { + expect(() => parseManagedConfigEnv(docWith([remoteHost({ runnerLifecycleMode: "inherit" })]))) + .toThrow(/"environments\[0\].runnerLifecycleMode" must be "warm" or "per_turn"/); + }); + it("does not compare the manifest id with autoInstall catalog keys (boot checks the catalog)", () => { expect(parseManagedConfigEnv(docWith([remoteHost()]))?.pluginEnvironments[0]?.pluginKey).toBe(PLUGIN_KEY); }); diff --git a/server/src/__tests__/managed-plugin-environments.test.ts b/server/src/__tests__/managed-plugin-environments.test.ts index 023579108d5..d243bad233d 100644 --- a/server/src/__tests__/managed-plugin-environments.test.ts +++ b/server/src/__tests__/managed-plugin-environments.test.ts @@ -92,7 +92,10 @@ const support = await getEmbeddedPostgresTestSupport(); manifestJson: { agentLifecycle: true, capabilities: ["agents.lifecycle.manage", "environment.drivers.register"], - environmentDrivers: [{ driverKey: "tasks", requiresAgent: true, supportsTasks: true }], + environmentDrivers: [ + { driverKey: "tasks", requiresAgent: true, supportsTasks: true }, + { driverKey: "other", requiresAgent: true, supportsTasks: true }, + ], } as never, }); }); @@ -240,6 +243,14 @@ const support = await getEmbeddedPostgresTestSupport(); expect(await instanceDefault()).toBeNull(); }); + it("persists the configured Runner lifecycle mode on boot and on change", async () => { + for (const runnerLifecycleMode of ["per_turn", "warm"]) { + await boot([{ ...remoteHostEntry, runnerLifecycleMode }]); + const [row] = await pluginRows(); + expect(row?.config).toMatchObject({ runnerLifecycleMode, driverConfig: { normalized: true } }); + } + }); + it("archives the row while the plugin is down and reactivates it when the worker recovers", async () => { await boot(); running = false; @@ -357,15 +368,28 @@ const support = await getEmbeddedPostgresTestSupport(); expect(await instanceDefault()).toBeNull(); }); - it("prepares a new agent that follows the default with the plugin, and one set to the sandbox without it", async () => { - await boot(); + it("uses the same environment for lifecycle plugin selection and the provisioning request", async () => { + await boot([defaultEntry, { ...remoteHostEntry, name: "Other Host", driverKey: "other" }]); + const other = await environmentService(db).findManagedPluginEnvironment({ pluginKey: PLUGIN_KEY, driverKey: "other" }); + expect(other).toBeDefined(); const sandboxId = await sandboxRow(); const companyId = await company(); - const selection = async (id: string) => - createLifecycleDriver(db, { call } as never) - .requiredPluginIds((await createLifecycleStore(db, createAgentLifecycleEffects()).get(id))!); - expect(await selection(await agent(companyId, null))).toEqual([pluginId]); - expect(await selection(await agent(companyId, sandboxId))).toEqual([]); + const invoke = vi.fn(async (_pluginId: string, _method: string, request: { operationId: string; version: number }) => + ({ operationId: request.operationId, version: request.version, status: "complete" })); + const driver = createLifecycleDriver(db, { call: invoke } as never); + const store = createLifecycleStore(db, createAgentLifecycleEffects()); + for (const environmentId of [null, other!.id, sandboxId]) { + const id = await agent(companyId, environmentId, { lifecycleState: "preparing" }); + await db.update(agents).set({ + lifecycleOperation: { id: randomUUID(), hostComplete: false, completedPluginIds: [], attempts: 0 }, + }).where(eq(agents.id, id)); + const snapshot = (await store.get(id))!; + expect(await driver.requiredPluginIds(snapshot)).toEqual(environmentId === sandboxId ? [] : [pluginId]); + await expect(driver.runPlugin(snapshot, pluginId)).resolves.toBe("complete"); + } + expect(invoke.mock.calls[0]?.[2]).toMatchObject({ phase: "preparing", environmentDriverKey: "tasks" }); + expect(invoke.mock.calls[1]?.[2]).toMatchObject({ phase: "preparing", environmentDriverKey: "other" }); + expect(invoke.mock.calls[2]?.[2]).not.toHaveProperty("environmentDriverKey"); }); }); }); diff --git a/server/src/services/agent-lifecycle-driver.ts b/server/src/services/agent-lifecycle-driver.ts index 20fe17f001b..a74ff0c5115 100644 --- a/server/src/services/agent-lifecycle-driver.ts +++ b/server/src/services/agent-lifecycle-driver.ts @@ -15,6 +15,15 @@ import { AGENT_LIFECYCLE_STOP_REASON, COMPANY_ARCHIVED_STOP_REASON } from "./gov export function createLifecycleDriver(db: Db, manager: PluginWorkerManager): LifecycleDriver { const { verify } = agentHarnessVerificationService(db, manager); const heartbeat = heartbeatService(db, { pluginWorkerManager: manager }); + + async function resolveAgentEnvironment(agent: { id: string; companyId: string }) { + const [placement] = await db.select({ environmentId: agents.defaultEnvironmentId }).from(agents) + .where(and(eq(agents.id, agent.id), eq(agents.companyId, agent.companyId))); + const environmentId = placement?.environmentId ?? (await instanceSettingsService(db).get()).defaultEnvironmentId; + const [environment] = environmentId ? await db.select().from(environments).where(eq(environments.id, environmentId)) : []; + return environment; + } + return { async onReady(agent) { await db.transaction(tx => promoteDeferredWorkIntents(tx, { companyId: agent.companyId, trigger: "pause_lifted" })); @@ -27,9 +36,7 @@ export function createLifecycleDriver(db: Db, manager: PluginWorkerManager): Lif .where(and(eq(pluginCompanySettings.companyId, agent.companyId), eq(pluginCompanySettings.enabled, false))); const candidates = installed.filter(plugin => !disabled.some(row => row.pluginId === plugin.id) && plugin.manifestJson.agentLifecycle && plugin.manifestJson.capabilities.includes("agents.lifecycle.manage")); - const [row] = await db.select({ environmentId: agents.defaultEnvironmentId }).from(agents).where(eq(agents.id, agent.id)); - const environmentId = row?.environmentId ?? (await instanceSettingsService(db).get()).defaultEnvironmentId; - const [environment] = environmentId ? await db.select().from(environments).where(eq(environments.id, environmentId)) : []; + const environment = await resolveAgentEnvironment(agent); if (selected !== null) { const added = candidates.filter(plugin => pluginServesAgentEnvironment(plugin, environment) && !selected.includes(plugin.id)); return [...selected, ...added.map(plugin => plugin.id)]; @@ -47,8 +54,11 @@ export function createLifecycleDriver(db: Db, manager: PluginWorkerManager): Lif const secrets = agentInstanceSecretService(db); const instanceSecrets = ["preparing", "resuming"].includes(agent.lifecycleState) ? await secrets.read({ companyId: agent.companyId, agentId: agent.id, pluginId }) : {}; + const environment = await resolveAgentEnvironment(agent); + const environmentDriverKey = pluginServesAgentEnvironment(plugin, environment) && typeof environment?.config?.driverKey === "string" + ? environment.config.driverKey : undefined; const request = { companyId: agent.companyId, agentId: agent.id, operationId, version: agent.lifecycleVersion, phase: agent.lifecycleState, - instanceSecrets }; + ...(environmentDriverKey ? { environmentDriverKey } : {}), instanceSecrets }; const result = await manager.call(plugin.id, "agentLifecycle", request, 30_000); if (!result || result.operationId !== operationId || result.version !== agent.lifecycleVersion || !["complete", "pending"].includes(result.status)) { throw Object.assign(new Error("Invalid lifecycle result"), { code: "invalid_lifecycle_result" }); diff --git a/server/src/services/managed-config-capabilities.json b/server/src/services/managed-config-capabilities.json index 74b8c566409..bd24f0fc0e0 100644 --- a/server/src/services/managed-config-capabilities.json +++ b/server/src/services/managed-config-capabilities.json @@ -1 +1 @@ -{ "schemaVersion": 1, "capabilities": ["pluginEnvironments"] } +{ "schemaVersion": 1, "capabilities": ["pluginEnvironments", "pluginEnvironmentRunnerLifecycleMode"] } diff --git a/server/src/services/managed-config-capabilities.test.ts b/server/src/services/managed-config-capabilities.test.ts index db97d78366b..2c1c4d4f6db 100644 --- a/server/src/services/managed-config-capabilities.test.ts +++ b/server/src/services/managed-config-capabilities.test.ts @@ -21,7 +21,7 @@ describe("managed-config-capabilities.json", () => { it("keeps the published contract", () => { expect(JSON.parse(readFileSync(capabilitiesFile, "utf8"))).toEqual({ schemaVersion: 1, - capabilities: ["pluginEnvironments"], + capabilities: ["pluginEnvironments", "pluginEnvironmentRunnerLifecycleMode"], }); }); }); diff --git a/server/src/services/managed-config.ts b/server/src/services/managed-config.ts index 0e39ff40b1b..0aa437b26cc 100644 --- a/server/src/services/managed-config.ts +++ b/server/src/services/managed-config.ts @@ -95,7 +95,10 @@ export const MANAGED_ENVIRONMENT_DRIVERS = ["sandbox", "plugin"] as const; * including `instanceDefault`. */ export const MANAGED_CONFIG_CAPABILITIES_SCHEMA_VERSION = 1; -export const MANAGED_CONFIG_CAPABILITIES = ["pluginEnvironments"] as const; +export const MANAGED_CONFIG_CAPABILITIES = [ + "pluginEnvironments", + "pluginEnvironmentRunnerLifecycleMode", +] as const; export type ManagedConfigCapability = (typeof MANAGED_CONFIG_CAPABILITIES)[number]; function supportsCapability(capability: ManagedConfigCapability): boolean { @@ -126,6 +129,7 @@ export interface ManagedPluginEnvironmentSpec { driverKey: string; /** Driver config, validated by the plugin at ensure time; never carries secrets. */ driverConfig: Readonly>; + runnerLifecycleMode?: "warm" | "per_turn"; /** * Fill the instance default with this environment when the default is * unset (or names the local environment or a deleted one), before the @@ -230,6 +234,7 @@ const PLUGIN_ENTRY_KEYS = [ "pluginKey", "driverKey", "driverConfig", + "runnerLifecycleMode", "instanceDefault", ] as const; /** Same rule as the plugin environment config schema in `environment-config.ts`. */ @@ -367,6 +372,10 @@ function parseManagedEnvironmentsSection( } pluginDrivers.add(pair); const driverConfig = readSecretFreeObject(entry.driverConfig, `${at}.driverConfig`); + const runnerLifecycleMode = entry.runnerLifecycleMode; + if (runnerLifecycleMode !== undefined && runnerLifecycleMode !== "warm" && runnerLifecycleMode !== "per_turn") { + fail(`"${at}.runnerLifecycleMode" must be "warm" or "per_turn"`); + } if (entry.instanceDefault !== undefined && typeof entry.instanceDefault !== "boolean") { fail(`"${at}.instanceDefault" must be a boolean when present (got ${describeJsonValue(entry.instanceDefault)})`); } @@ -387,6 +396,7 @@ function parseManagedEnvironmentsSection( pluginKey, driverKey, driverConfig: Object.freeze(driverConfig), + ...(runnerLifecycleMode ? { runnerLifecycleMode } : {}), instanceDefault, }) as ManagedPluginEnvironmentSpec, ); diff --git a/server/src/services/managed-environments.ts b/server/src/services/managed-environments.ts index 7d055bdb8fb..66db1d86aa8 100644 --- a/server/src/services/managed-environments.ts +++ b/server/src/services/managed-environments.ts @@ -555,6 +555,7 @@ export async function applyManagedEnvironments( pluginKey: spec.pluginKey, driverKey: spec.driverKey, driverConfig: { ...spec.driverConfig }, + ...(spec.runnerLifecycleMode ? { runnerLifecycleMode: spec.runnerLifecycleMode } : {}), workerManager, }); diff --git a/server/src/services/managed-plugin-environments.ts b/server/src/services/managed-plugin-environments.ts index a3450722f9a..10fff56146c 100644 --- a/server/src/services/managed-plugin-environments.ts +++ b/server/src/services/managed-plugin-environments.ts @@ -43,6 +43,7 @@ export interface ManagedPluginEnvironmentInput { pluginKey: string; driverKey: string; driverConfig?: Record; + runnerLifecycleMode?: "warm" | "per_turn"; /** Runs the plugin's own config validation (`environmentValidateConfig`). */ workerManager: Pick; } @@ -79,7 +80,8 @@ function servesPair(row: EnvironmentRow, input: { pluginKey: string; driverKey: async function validatedDriverConfig(db: Db, input: ManagedPluginEnvironmentInput): Promise { const normalized = normalizeEnvironmentConfig({ driver: "plugin", - config: { pluginKey: input.pluginKey, driverKey: input.driverKey, driverConfig: input.driverConfig ?? {} }, + config: { pluginKey: input.pluginKey, driverKey: input.driverKey, driverConfig: input.driverConfig ?? {}, + ...(input.runnerLifecycleMode ? { runnerLifecycleMode: input.runnerLifecycleMode } : {}) }, }) as unknown as PluginEnvironmentConfig; return await validatePluginEnvironmentDriverConfig({ db, diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index 99baee324b4..a850e464474 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -366,7 +366,7 @@ "packages/shared/src/types/activity.ts": "9d383f85775bf3657a7f9bdfb32a6e58e58c12a3", "packages/shared/src/types/adapter-registry.ts": "bd9b0a1f7980bf444f7f3d75a4687874014c4bca", "packages/shared/src/types/adapter-skills.ts": "ac77f7e013e8fb8de6fcbe916b7f7923554de815", - "packages/shared/src/types/agent-lifecycle.ts": "3ff9d17a2b7e1710463961b50e8e61014f80a55a", + "packages/shared/src/types/agent-lifecycle.ts": "dcc5105d57856cc8ca34a122cf54117c950184ea", "packages/shared/src/types/agent.adapter-auth-session.test.ts": "d651511d78cb44b29940252df6138cd202e0ab45", "packages/shared/src/types/agent.ts": "11f5dbdf5b4c16271b5d79e22b159f97be68e896", "packages/shared/src/types/app-definition.ts": "f55fad80e9c765e16a3a59f694bdb0764940d968",