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",