From db73178bcf21c9d9664410b471968d5ffdad08fd Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Mon, 16 Nov 2026 08:24:47 -0800 Subject: [PATCH] fix(heartbeat): keep saved sessions across config edits the provider thread cannot see (#21862) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - A heartbeat run resumes the agent's saved task session, which holds the provider thread and its history. > - Before resume, Paperclip compares a fingerprint of the effective run configuration with the fingerprint that the session saved. A difference discards the thread. > - The fingerprint hashed the agent config revision row (id, changed keys, time). Every saved agent edit therefore discarded the thread, also an edit that set a value back to what it was. > - The fingerprint also hashed settings that never reach the thread or the native execution input, for example turn timeouts, wake scheduling, and the environment row's update time. > - This pull request removes those inputs from the fingerprint, classifies every input with its reason, and adds backstop tests so that a new input cannot join or leave the fingerprint without a decision. > - The benefit is that agents keep their thread history across edits that cannot change what the thread saw or may do, while real changes still start a new thread. ## Linked Issues or Issue Description Related: #9977 (semantic task-session fingerprints, open) and #8797 (added the effective run config fingerprint). **What happened?** An operator changed an agent's warm idle window from 60000 to unset, and then back to 60000, between two turns on the same issue. The next run logged `Skipping saved session resume for task "" because effective run configuration changed: adapter.` Only the `adapter` category changed, because the new config revision row was in it. The adapter config itself was identical. The run started a new provider thread. The environment lease was reused, so the run stopped the retained remote task before it started a new one. That stop raced the task's exit, and the run failed with `Plugin Runner termination is unconfirmed; reconcile the saved task`. An automatic retry then succeeded on a fresh environment. **Expected behavior** An edit that cannot change what the provider thread saw or may do, and cannot change the native execution input, keeps the saved session. An edit to the model, provider, active permission mode, lifecycle mode or warm idle window, instructions, skills, environment, secrets, or another thread input still starts a new session. **Steps to reproduce** 1. Run an agent turn on an issue so that the task session saves its fingerprint. 2. Save an agent config edit that does not change a thread input, for example set `adapterConfig.idleTimeoutMs` to another value and back, or rename the agent. 3. Wake the agent on the same issue. On master the run log shows "effective run configuration changed: adapter" and the run starts a new thread. ## What Changed - New `server/src/services/heartbeat/session-fingerprint-inputs.ts`. It classifies each fingerprint input as kept or excluded, with the reason: - agent config revision fields (`CONFIG_REVISION_FIELDS`); - `paperclip_runner` adapter config keys; - top-level environment driver config keys; - agent runtime config keys; - selected-environment and environment-selection fields. - The session fingerprint no longer hashes these inputs: - the config revision row (id, changed keys, time); - for `paperclip_runner`: `timeoutSec`, `graceSec`, the permission keys of providers that are not selected, and `search` when the provider is not Codex; - `runtimeConfig.heartbeat` (wake scheduling, concurrency, daily caps, max-turn continuation); - the selected environment's `configRevisionAt` (row update time) and the `selectionSource`; - environment config `archiveOnRelease`, `streamRunLogs`, and `timeoutMs` (sandbox RPC timeout). - Unknown adapter and runtime config keys are still hashed. A missing classification can only keep the old reset behavior; it cannot skip a reset. - Lifecycle inputs stay in the fingerprint: `lifecycleMode`, `idleTimeoutMs`, and the environment's `runnerLifecycleMode`, `runnerIdleTimeoutMs`, and `reuseLease`. They become `session.lifecyclePolicy`, which the native session digest compares before a follow-up turn attaches to its warm Runner. A kept session with a different policy would be refused (`warm_recovery_refused=execution_mismatch`). - Session preparation accepts a saved fingerprint built with the previous composition (`legacyComposition`) for the same inputs. The upgrade therefore does not discard every saved session once. The run then saves the new fingerprint. - Backstop tests in `session-fingerprint-inputs.test.ts`: - every agent revision field, runner config schema field, provider permission key, and environment driver config key has a classification; - the shape of each hashed category is pinned, so a new field cannot reach the fingerprint without a decision; - every runner key classified as excluded leaves the native provider input and the lifecycle policy unchanged (this test fails if `idleTimeoutMs` is reclassified as excluded); - behavior tests for each exclusion and for the thread and lifecycle inputs that must still reset; - a pinned fingerprint proves that the legacy composition reproduces the master fingerprint exactly. - `ai-connection-session.test.ts`: two tests used a rename or a `heartbeat` edit as the "unrelated change". They now use a model change or an unclassified runtime setting, and two new tests pin that a rename and a scheduling change keep the session. - `doc/heartbeat-internals.md` (Config Freshness) describes the rule and the backstop. The PR adds no code comments, as `CONTRIBUTING.md` requires; the reasons live in the classification tables and the doc. ## Verification - Red/green: on master, the exclusion cases, the category-shape pin, and the legacy acceptance case fail. With the change, all pass. - Backstop check: with `idleTimeoutMs` temporarily reclassified as excluded, the native-input test and the idle-window reset test fail. - Legacy bridge: I computed the fingerprint for one runner fixture and one `codex_local` fixture with master's `workspaces.ts` and with `legacyComposition: true` on this branch. The output files were byte-identical, category fingerprints included. The pinned test uses those values. - `cd server && npx vitest run src/services/heartbeat/session-fingerprint-inputs.test.ts src/__tests__/ai-connection-session.test.ts src/__tests__/heartbeat-workspace-session.test.ts src/__tests__/heartbeat-execution-configuration.test.ts src/__tests__/ai-connection-router.test.ts src/__tests__/native-session-resumption.test.ts src/__tests__/environment-service.test.ts`: 7 files, 397 tests, all pass. - `npx tsc --noEmit -p server`: no errors. - `pnpm verify` exited 2 (broader coverage needed), so the focused checks above and required CI give the coverage. ## Risks - Behavior change: an agent rename, role, title, icon, appearance, reports-to, capabilities, budget, or metadata edit no longer starts a new thread. Agent tools read these fields live at call time (`runner-semantic-authority.ts`, `paperclip-runner-tool-authority.ts`), so the thread never holds a frozen copy. - Behavior change: wake-scheduling and turn-timeout edits no longer start a new thread. Neither value is part of the native execution input, so warm Runner attachment is unaffected. - A warm idle window edit still starts a new thread. Setting it and setting it back between turns no longer does, because the revision row is not hashed. - The legacy bridge computes extra candidate fingerprints only when the saved fingerprint differs. It accepts a legacy fingerprint only for the same current inputs; it never widens what a reset protects. - During the transition, a real change on a session that still holds a legacy fingerprint can list extra categories in the reset reason. The reset decision is correct. - No schema or API change. The fingerprint version stays 1. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used in Claude Code with tool use (shell, file edit) and extended thinking. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- doc/heartbeat-internals.md | 2 + .../__tests__/ai-connection-session.test.ts | 19 +- server/src/lib/agent-records.ts | 2 +- server/src/services/environment-config.ts | 7 + .../session-fingerprint-inputs.test.ts | 248 ++++++++++++++++++ .../heartbeat/session-fingerprint-inputs.ts | 163 ++++++++++++ .../services/heartbeat/session-preparation.ts | 30 ++- server/src/services/heartbeat/workspaces.ts | 17 +- 8 files changed, 464 insertions(+), 24 deletions(-) create mode 100644 server/src/services/heartbeat/session-fingerprint-inputs.test.ts create mode 100644 server/src/services/heartbeat/session-fingerprint-inputs.ts diff --git a/doc/heartbeat-internals.md b/doc/heartbeat-internals.md index 71f32893afc..59be8eafd62 100644 --- a/doc/heartbeat-internals.md +++ b/doc/heartbeat-internals.md @@ -78,6 +78,8 @@ configuration variables; task bindings cannot override them. When effective run config changes, Paperclip may intentionally skip a saved adapter session, refresh persisted workspace runtime config, replace a reused execution workspace, or avoid reusing a sandbox/environment lease. Fresh execution can lose adapter-specific session, workspace, or sandbox state; correctness of the next run's config takes priority over continuity. Plain environment values affect freshness through value hashes; run result JSON and workspace operation logs expose only the non-sensitive freshness decision categories, without storing secret values, full env maps, provider credentials, or private path details. +The saved-session fingerprint covers only inputs that can change what the provider thread saw or may do, or what the native session digest compares before a follow-up turn attaches to its warm Runner. It leaves out the agent config revision row itself (its id and time), agent identity and display fields that tools read live, turn timeouts, the legacy kill grace, permission keys of a provider that is not selected, wake scheduling (`runtimeConfig.heartbeat`), the environment row's update time and selection source, and the environment's release, log-streaming, and RPC-timeout settings. Lifecycle inputs stay in: the lifecycle mode, the agent and environment warm idle windows, and the environment's lease reuse, because they become `session.lifecyclePolicy`, and a kept session with a different policy cannot attach to its warm Runner. `server/src/services/heartbeat/session-fingerprint-inputs.ts` classifies every input with the reason. Its tests fail when an agent revision field, a runner config schema field, a provider permission key, or an environment config key appears without a classification, when a new field reaches a hashed category, or when an excluded runner key reaches the native execution input. An unknown adapter or runtime config key is hashed. A session saved with the previous fingerprint composition is accepted once for the same inputs, so an upgrade does not discard saved sessions. + An explicit `reuse_existing` Git workspace keeps its recorded source repository, including after its project-workspace row is deleted or the project primary changes. The server verifies the original company, project, repository origin, and worktree registration before reuse. It does not attach a deleted association to the new primary. A conflicting explicit project-workspace selection, missing source identity, or an unverified legacy local checkout blocks the run. Restore the original source. Before intentionally clearing the existing-workspace binding to choose a new repository, review and preserve its retained work. Missing worktrees may be reconstructed only from the verified original source; current project defaults are not a fallback. ## Heartbeat Service Extractions diff --git a/server/src/__tests__/ai-connection-session.test.ts b/server/src/__tests__/ai-connection-session.test.ts index 81bed1e2c4c..dbd1b13fe0f 100644 --- a/server/src/__tests__/ai-connection-session.test.ts +++ b/server/src/__tests__/ai-connection-session.test.ts @@ -40,22 +40,33 @@ describe("AI pool session adoption", () => { const switchPool = revision("revision-3", { mode: "router", connectionId: "previous-pool" }, pool); expect((await decision({ agentRuntimeConfig: { aiConnection: binding }, agentConfigRevision: aiConnectionRevisionMetadata(first) }, { agentConfigRevision: aiConnectionRevisionMetadata(switchPool) }, { revisions: [switchPool, adoption, first] })).reset).toBe(false); }); - it("retains resets when the same edit also changes unrelated configuration", async () => { + it("retains resets when the same edit also changes a setting the thread uses", async () => { + const first = revision("revision-1", null, binding); + const edit = revision("revision-2", binding, pool, { adapterConfig: { model: "gpt-5.6-terra" } }); + expect(aiConnectionOnlyConfigRevision(edit)).toBe(false); + expect((await decision({ agentRuntimeConfig: { aiConnection: binding }, agentConfigRevision: aiConnectionRevisionMetadata(first) }, { agentConfigRevision: aiConnectionRevisionMetadata(edit), effectiveAdapterConfig: { ...config, model: "gpt-5.6-terra" } }, { revisions: [edit, first] })).reset).toBe(true); + }); + it("keeps the session when the same edit also renames the agent", async () => { const first = revision("revision-1", null, binding); const edit = revision("revision-2", binding, pool, { name: "Renamed agent" }); expect(aiConnectionOnlyConfigRevision(edit)).toBe(false); - expect((await decision({ agentRuntimeConfig: { aiConnection: binding }, agentConfigRevision: aiConnectionRevisionMetadata(first) }, { agentConfigRevision: aiConnectionRevisionMetadata(edit) }, { revisions: [edit, first] })).reset).toBe(true); + expect((await decision({ agentRuntimeConfig: { aiConnection: binding }, agentConfigRevision: aiConnectionRevisionMetadata(first) }, { agentConfigRevision: aiConnectionRevisionMetadata(edit) }, { revisions: [edit, first] })).reset).toBe(false); }); it("does not bridge a stale revision over a newer runtime settings change", async () => { const first = revision("revision-1", null, binding); const adoption = revision("revision-2", binding, pool); - expect((await decision({ agentRuntimeConfig: { aiConnection: binding }, agentConfigRevision: aiConnectionRevisionMetadata(first) }, { agentRuntimeConfig: { aiConnection: pool, heartbeat: { enabled: false } }, agentConfigRevision: aiConnectionRevisionMetadata(adoption) }, { revisions: [adoption, first] })).reset).toBe(true); + expect((await decision({ agentRuntimeConfig: { aiConnection: binding }, agentConfigRevision: aiConnectionRevisionMetadata(first) }, { agentRuntimeConfig: { aiConnection: pool, futureSetting: true }, agentConfigRevision: aiConnectionRevisionMetadata(adoption) }, { revisions: [adoption, first] })).reset).toBe(true); + }); + it("keeps the session across a wake-scheduling change after a binding edit", async () => { + const first = revision("revision-1", null, binding); + const adoption = revision("revision-2", binding, pool); + expect((await decision({ agentRuntimeConfig: { aiConnection: binding }, agentConfigRevision: aiConnectionRevisionMetadata(first) }, { agentRuntimeConfig: { aiConnection: pool, heartbeat: { enabled: false } }, agentConfigRevision: aiConnectionRevisionMetadata(adoption) }, { revisions: [adoption, first] })).reset).toBe(false); }); it.each([ { effectiveAdapterConfig: { ...config, model: "gpt-5.6-terra" } }, { effectiveAdapterConfig: { ...config, provider: "acpx", acpxAgent: "codex" } }, { effectiveAdapterConfig: { ...config, env: { ...config.env, OTHER: "changed" } } }, - { agentRuntimeConfig: { aiConnection: pool, heartbeat: { maxConcurrentRuns: 2 } } }, + { agentRuntimeConfig: { aiConnection: pool, futureSetting: true } }, { workspaceConfig: { effectiveMode: "isolated_workspace" } }, ])("preserves normal resets for effective settings changes: %j", async next => { expect((await decision({ agentRuntimeConfig: { aiConnection: binding } }, next)).reset).toBe(true); diff --git a/server/src/lib/agent-records.ts b/server/src/lib/agent-records.ts index f5b7500cabf..fccfe212605 100644 --- a/server/src/lib/agent-records.ts +++ b/server/src/lib/agent-records.ts @@ -20,7 +20,7 @@ export function createToken() { return `pcp_${randomBytes(24).toString("hex")}`; } -const CONFIG_REVISION_FIELDS = [ +export const CONFIG_REVISION_FIELDS = [ "name", "role", "title", diff --git a/server/src/services/environment-config.ts b/server/src/services/environment-config.ts index 3fcb01fc93e..fd592f270b5 100644 --- a/server/src/services/environment-config.ts +++ b/server/src/services/environment-config.ts @@ -138,6 +138,13 @@ const pluginEnvironmentConfigSchema = z.object({ driverConfig: z.record(z.string(), z.unknown()).optional().default({}), }).strict(); +export const ENVIRONMENT_CONFIG_SCHEMA_KEYS = { + ssh: Object.keys(sshEnvironmentConfigPersistenceSchema.shape), + fakeSandbox: Object.keys(fakeSandboxEnvironmentConfigSchema.shape), + pluginSandbox: Object.keys(pluginSandboxEnvironmentConfigSchema.shape), + plugin: Object.keys(pluginEnvironmentConfigSchema.shape), +} as const; + export type ParsedEnvironmentConfig = | { driver: "local"; config: LocalEnvironmentConfig } | { driver: "ssh"; config: SshEnvironmentConfig } diff --git a/server/src/services/heartbeat/session-fingerprint-inputs.test.ts b/server/src/services/heartbeat/session-fingerprint-inputs.test.ts new file mode 100644 index 00000000000..39ede31d455 --- /dev/null +++ b/server/src/services/heartbeat/session-fingerprint-inputs.test.ts @@ -0,0 +1,248 @@ +import { describe, expect, it } from "vitest"; +import { PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES } from "@paperclipai/adapter-utils"; +import { getServerAdapter } from "../../adapters/registry.js"; +import { resolvePaperclipRunnerNativeProviderInput, resolvePaperclipRunnerProviderProfile } from "../native-runtime/provider-profile.js"; +import { resolveHeartbeatNativeLifecyclePolicy } from "./native-lifecycle.js"; +import { CONFIG_REVISION_FIELDS } from "../../lib/agent-records.js"; +import { ENVIRONMENT_CONFIG_SCHEMA_KEYS } from "../environment-config.js"; +import { + AGENT_REVISION_FIELD_SESSION_INPUTS, + AGENT_RUNTIME_CONFIG_SESSION_INPUTS, + ENVIRONMENT_CONFIG_SESSION_INPUTS, + ENVIRONMENT_SELECTION_SESSION_INPUTS, + PAPERCLIP_RUNNER_ADAPTER_CONFIG_SESSION_INPUTS, + SELECTED_ENVIRONMENT_SESSION_INPUTS, +} from "./session-fingerprint-inputs.js"; +import { + buildEffectiveRunSessionConfigMetadata, + buildSessionConfigCategoryValues, + resolveTaskSessionConfigFreshness, +} from "./workspaces.js"; + +const CLASSIFY = + "Classify it in session-fingerprint-inputs.ts: kept if a change can alter what the provider thread saw or may do, " + + "excluded (with the reason) if it cannot. An unclassified field discards saved sessions blindly or keeps them unsafely."; + +const unclassified = (keys: Iterable, table: Record) => + [...new Set(keys)].filter(key => !Object.hasOwn(table, key)).sort(); + +describe("session fingerprint input classification (backstop)", () => { + it("classifies every agent field that records a configuration revision", () => { + expect(unclassified(CONFIG_REVISION_FIELDS, AGENT_REVISION_FIELD_SESSION_INPUTS), CLASSIFY).toEqual([]); + expect(Object.keys(AGENT_REVISION_FIELD_SESSION_INPUTS).sort()).toEqual([...CONFIG_REVISION_FIELDS].sort()); + }); + + it("classifies every paperclip_runner config schema field and provider permission key", async () => { + const schema = await getServerAdapter("paperclip_runner").getConfigSchema?.(); + const schemaKeys = (schema?.fields ?? []).map(field => field.key); + expect(schemaKeys.length).toBeGreaterThan(0); + const permissionKeys = Object.values(PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES) + .flatMap(capability => capability.configurable ? [capability.configKey] : []); + expect(unclassified([...schemaKeys, ...permissionKeys], PAPERCLIP_RUNNER_ADAPTER_CONFIG_SESSION_INPUTS), CLASSIFY).toEqual([]); + }); + + it("classifies every top-level environment driver config key, and only real keys", () => { + const schemaKeys = Object.values(ENVIRONMENT_CONFIG_SCHEMA_KEYS).flat(); + expect(unclassified(schemaKeys, ENVIRONMENT_CONFIG_SESSION_INPUTS), CLASSIFY).toEqual([]); + expect(Object.keys(ENVIRONMENT_CONFIG_SESSION_INPUTS).filter(key => !schemaKeys.includes(key))).toEqual([]); + }); + + it.each([ + { provider: "codex", model: "gpt-5.4-mini", codexPermissionMode: "never", lifecycleMode: "warm", idleTimeoutMs: 60_000 }, + { provider: "opencode", model: "openai/gpt-5.4-mini", opencodePermissionMode: "allow" }, + ])("keeps every excluded runner key out of the native execution input: %j", base => { + const nativeInputs = (config: Record) => { + const backend = resolvePaperclipRunnerProviderProfile(config).backend; + return { + provider: resolvePaperclipRunnerNativeProviderInput({ backend, adapterConfig: config }), + lifecyclePolicy: resolveHeartbeatNativeLifecyclePolicy({ + adapterType: "paperclip_runner", backend, agentMode: config.lifecycleMode, agentIdleTimeoutMs: config.idleTimeoutMs, + managedAiSelected: false, taskOwned: true, localTarget: false, + }), + }; + }; + const reference = nativeInputs(base); + const inertKeys = [ + ...Object.entries(PAPERCLIP_RUNNER_ADAPTER_CONFIG_SESSION_INPUTS).filter(([, value]) => value.kind === "excluded").map(([key]) => key), + ...Object.values(PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES).flatMap(capability => capability.configurable ? [capability.configKey] : []) + .filter(key => key !== PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES[base.provider as "codex" | "opencode"].configKey), + ]; + expect(inertKeys.length).toBeGreaterThan(0); + for (const key of inertKeys) { + expect(nativeInputs({ ...base, [key]: 12_345 }), `${key} reaches the native execution input; keep it in the fingerprint`).toEqual(reference); + } + expect(nativeInputs({ ...base, idleTimeoutMs: 120_000, lifecycleMode: "warm" }).lifecyclePolicy) + .not.toEqual(nativeInputs({ ...base, idleTimeoutMs: 60_000, lifecycleMode: "warm" }).lifecyclePolicy); + }); + + it("pins the shape of every hashed category, so a new field cannot join the fingerprint unclassified", () => { + const values = buildSessionConfigCategoryValues({ + adapterType: "paperclip_runner", + agentIdentityKeyId: "key-1", + effectiveAdapterConfig: { provider: "codex", model: "model-a" }, + agentRuntimeConfig: { aiConnection: { mode: "shared" }, heartbeat: { enabled: true } }, + instructions: { configured: true }, + issueOverrides: { model: "model-b" }, + workspaceConfig: { requestedMode: "agent_default", effectiveMode: "agent_default" }, + environment: { + selectionSource: "agent_default", + selectedEnvironmentId: "environment-1", + selectedEnvironment: { id: "environment-1", driver: "plugin", config: { pluginKey: "p" }, configRevisionAt: "2099-01-01T00:00:00.000Z" }, + executionPolicy: { mode: "default" }, + }, + environmentEnv: { A: "1" }, + projectEnv: { B: "2" }, + routineEnv: { C: "3" }, + secretManifest: [], + runtimeSkills: [], + agentConfigRevision: { id: "revision-1", changedKeys: ["adapterConfig"], configRevisionAt: "2099-01-01T00:00:00.000Z" }, + }); + expect(Object.keys(values).sort(), CLASSIFY).toEqual([ + "adapter", "adapterConfig", "agentRuntimeConfig", "envBindings", "environment", "instructions", + "issueOverrides", "runtimeSkills", "secrets", "workspaceConfig", + ]); + expect(Object.keys(values.adapter).sort(), CLASSIFY).toEqual(["adapterType", "agentIdentityKeyId"]); + const environment = values.environment as Record; + expect(Object.keys(environment).sort(), CLASSIFY).toEqual( + Object.entries(ENVIRONMENT_SELECTION_SESSION_INPUTS).filter(([, value]) => value.kind === "kept").map(([key]) => key).sort(), + ); + expect(Object.keys(environment.selectedEnvironment as object).sort(), CLASSIFY).toEqual( + Object.entries(SELECTED_ENVIRONMENT_SESSION_INPUTS).filter(([, value]) => value.kind === "kept").map(([key]) => key).sort(), + ); + expect(Object.keys(values.agentRuntimeConfig as object)).toEqual(["aiConnection"]); + expect(Object.keys(values.envBindings).sort()).toEqual(["environment", "project", "routine"]); + expect(AGENT_RUNTIME_CONFIG_SESSION_INPUTS.heartbeat.kind).toBe("excluded"); + }); +}); + +type MetadataInput = Parameters[0]; + +const baseInput: MetadataInput = { + adapterType: "paperclip_runner", + effectiveAdapterConfig: { + provider: "codex", model: "model-a", codexPermissionMode: "never", lifecycleMode: "warm", + idleTimeoutMs: 60_000, timeoutSec: 0, graceSec: 15, opencodePermissionMode: "allow", acpxPermissionMode: "approve-all", + }, + agentRuntimeConfig: { aiConnection: { mode: "shared", grantId: "grant-1" }, heartbeat: { enabled: false, maxConcurrentRuns: 20 } }, + issueOverrides: null, + workspaceConfig: { requestedMode: "agent_default", effectiveMode: "agent_default" }, + environment: { + selectionSource: "agent_default", + selectedEnvironmentId: "environment-1", + selectedEnvironment: { + id: "environment-1", driver: "plugin", configRevisionAt: "2099-01-01T00:00:00.000Z", + config: { pluginKey: "plugin-a", driverKey: "tasks", driverConfig: { image: "image-a" }, runnerIdleTimeoutMs: 60_000 }, + }, + }, + environmentEnv: null, + projectEnv: null, + routineEnv: null, + runtimeSkills: [], + agentConfigRevision: { id: "revision-1", changedKeys: ["adapterConfig"], configRevisionAt: "2099-01-01T00:00:00.000Z" }, +}; + +const withAdapterConfig = (patch: Record): Partial => ({ + effectiveAdapterConfig: { ...baseInput.effectiveAdapterConfig, ...patch }, +}); +const withSelectedEnvironment = (patch: Record, configPatch: Record = {}): Partial => { + const environment = baseInput.environment as { selectedEnvironment: { config: Record } & Record }; + return { environment: { ...(baseInput.environment as object), selectedEnvironment: { + ...environment.selectedEnvironment, ...patch, config: { ...environment.selectedEnvironment.config, ...configPatch }, + } } }; +}; + +async function freshness(next: Partial, compatible: Partial[] = []) { + const saved = await buildEffectiveRunSessionConfigMetadata(baseInput); + const configMetadata = await buildEffectiveRunSessionConfigMetadata({ ...baseInput, ...next }); + const compatibleConfigMetadata = await Promise.all(compatible.map(input => buildEffectiveRunSessionConfigMetadata({ ...baseInput, ...next, ...input }))); + return resolveTaskSessionConfigFreshness({ + hasTaskSession: true, configuredModel: "model-a", configMetadata, compatibleConfigMetadata, + taskSessionParams: { + __paperclipConfiguredModel: "model-a", __paperclipConfigFingerprint: saved.fingerprint, + __paperclipConfigFingerprintVersion: saved.version, __paperclipConfigCategoryFingerprints: saved.categoryFingerprints, + }, + }); +} + +describe("session fingerprint keeps sessions across non-thread changes", () => { + it.each<[string, Partial]>([ + ["a new config revision, even one that restores the same values", + { agentConfigRevision: { id: "revision-2", changedKeys: ["adapterConfig"], configRevisionAt: "2099-01-02T00:00:00.000Z" } }], + ["a revision of display-only agent fields", { agentConfigRevision: { id: "revision-3", changedKeys: ["name", "icon"], configRevisionAt: "2099-01-03T00:00:00.000Z" } }], + ["the turn time limit", withAdapterConfig({ timeoutSec: 3600 })], + ["the legacy kill grace", withAdapterConfig({ graceSec: 30 })], + ["another provider's permission mode", withAdapterConfig({ opencodePermissionMode: "deny", acpxPermissionMode: "deny-all" })], + ["wake scheduling", { agentRuntimeConfig: { aiConnection: { mode: "shared", grantId: "grant-1" }, heartbeat: { enabled: true, intervalSec: 300 } } }], + ["the environment row's update time", withSelectedEnvironment({ configRevisionAt: "2099-02-01T00:00:00.000Z" })], + ["how the same environment was selected", { environment: { ...(baseInput.environment as object), selectionSource: "issue" } }], + ["the environment's release, log streaming, and RPC timeout settings", + withSelectedEnvironment({}, { archiveOnRelease: true, streamRunLogs: false, timeoutMs: 30_000 })], + ])("does not reset for %s", async (_label, next) => { + expect(await freshness(next)).toMatchObject({ reset: false, changedCategories: [] }); + }); + + it("drops Codex-only search for another provider but keeps it for Codex", async () => { + const opencode = { provider: "opencode", opencodePermissionMode: "allow" }; + const saved = await buildEffectiveRunSessionConfigMetadata({ ...baseInput, ...withAdapterConfig(opencode) }); + const next = await buildEffectiveRunSessionConfigMetadata({ ...baseInput, ...withAdapterConfig({ ...opencode, search: false }) }); + expect(next.fingerprint).toBe(saved.fingerprint); + expect((await freshness(withAdapterConfig({ search: false }))).reset).toBe(true); + }); +}); + +describe("session fingerprint still resets for thread changes", () => { + it.each<[string, Partial]>([ + ["the model", withAdapterConfig({ model: "model-b" })], + ["the provider", withAdapterConfig({ provider: "opencode" })], + ["the active provider's permission mode", withAdapterConfig({ codexPermissionMode: "on-request" })], + ["the lifecycle mode", withAdapterConfig({ lifecycleMode: "per_turn" })], + ["the warm idle window, which the native session digest compares", withAdapterConfig({ idleTimeoutMs: 300_000 })], + ["the environment's warm idle window", withSelectedEnvironment({}, { runnerIdleTimeoutMs: 300_000 })], + ["the environment's lease reuse, which can change the default lifecycle", withSelectedEnvironment({}, { reuseLease: true })], + ["the provider account", { agentRuntimeConfig: { aiConnection: { mode: "shared", grantId: "grant-2" }, heartbeat: { enabled: false, maxConcurrentRuns: 20 } } }], + ["an unclassified runtime setting", { agentRuntimeConfig: { aiConnection: { mode: "shared", grantId: "grant-1" }, futureSetting: true } }], + ["an unclassified adapter setting", withAdapterConfig({ futureSetting: true })], + ["the environment", { environment: { ...(baseInput.environment as object), selectedEnvironmentId: "environment-2" } }], + ["the plugin driver config", withSelectedEnvironment({}, { driverConfig: { image: "image-b" } })], + ["the environment's lifecycle mode", withSelectedEnvironment({}, { runnerLifecycleMode: "per_turn" })], + ])("resets for %s", async (_label, next) => { + expect((await freshness(next)).reset).toBe(true); + }); +}); + +describe("legacy session fingerprints", () => { + it("reproduces the fingerprint saved before non-thread inputs left it", async () => { + const input: MetadataInput = { + adapterType: "paperclip_runner", + effectiveAdapterConfig: { provider: "codex", model: "model-a", codexPermissionMode: "never", lifecycleMode: "warm", idleTimeoutMs: 60000, timeoutSec: 0, graceSec: 15, opencodePermissionMode: "allow" }, + agentRuntimeConfig: { aiConnection: { mode: "shared" }, heartbeat: { enabled: false } }, + issueOverrides: null, workspaceConfig: { requestedMode: "agent_default" }, + environment: { selectionSource: "agent_default", selectedEnvironmentId: "e1", selectedEnvironment: { + id: "e1", driver: "plugin", configRevisionAt: "2099-01-01T00:00:00.000Z", config: { pluginKey: "p", runnerIdleTimeoutMs: 60000, reuseLease: true }, + } }, + environmentEnv: null, projectEnv: null, routineEnv: null, runtimeSkills: [], + agentConfigRevision: { id: "r1", changedKeys: ["adapterConfig"], configRevisionAt: "2099-01-01T00:00:00.000Z" }, + }; + expect((await buildEffectiveRunSessionConfigMetadata({ ...input, legacyComposition: true })).fingerprint) + .toBe("v1:sha256:1fbf35727ca022f7abe258b6277419c7fb19f6f911d7b02e52670681479528b5"); + expect((await buildEffectiveRunSessionConfigMetadata({ ...input, adapterType: "codex_local", legacyComposition: true })).fingerprint) + .toBe("v1:sha256:59f18fe1541c686ab9d29476b1b0525ab492053ab7b4d5fbd910a5b7503ca203"); + }); + + it("accepts a session saved with the legacy composition for the same inputs, once", async () => { + const legacySaved = await buildEffectiveRunSessionConfigMetadata({ ...baseInput, legacyComposition: true }); + const current = await buildEffectiveRunSessionConfigMetadata(baseInput); + expect(legacySaved.fingerprint).not.toBe(current.fingerprint); + const decide = async (next: Partial) => resolveTaskSessionConfigFreshness({ + hasTaskSession: true, configuredModel: "model-a", + configMetadata: await buildEffectiveRunSessionConfigMetadata({ ...baseInput, ...next }), + compatibleConfigMetadata: [await buildEffectiveRunSessionConfigMetadata({ ...baseInput, ...next, legacyComposition: true })], + taskSessionParams: { + __paperclipConfiguredModel: "model-a", __paperclipConfigFingerprint: legacySaved.fingerprint, + __paperclipConfigFingerprintVersion: legacySaved.version, __paperclipConfigCategoryFingerprints: legacySaved.categoryFingerprints, + }, + }); + expect((await decide({})).reset).toBe(false); + expect((await decide({ agentConfigRevision: { id: "revision-2", changedKeys: ["adapterConfig"], configRevisionAt: "2099-01-02T00:00:00.000Z" } })).reset).toBe(true); + }); +}); diff --git a/server/src/services/heartbeat/session-fingerprint-inputs.ts b/server/src/services/heartbeat/session-fingerprint-inputs.ts new file mode 100644 index 00000000000..463d866c763 --- /dev/null +++ b/server/src/services/heartbeat/session-fingerprint-inputs.ts @@ -0,0 +1,163 @@ +import { + isPaperclipRunnerProvider, + PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES, +} from "@paperclipai/adapter-utils"; + +export type SessionFingerprintClassification = + | { kind: "kept"; reason: string } + | { kind: "excluded"; reason: string }; + +const kept = (reason: string): SessionFingerprintClassification => ({ kind: "kept", reason }); +const excluded = (reason: string): SessionFingerprintClassification => ({ kind: "excluded", reason }); + +const LIVE_AGENT_IDENTITY = + "Agent tools read this from the agent row at call time; the thread holds no frozen copy, and the native execution input does not carry it."; +const NATIVE_LIFECYCLE = + "Becomes part of session.lifecyclePolicy. The native session digest compares that policy before a follow-up turn attaches to its warm Runner, so a change needs a new session."; + +export const AGENT_REVISION_FIELD_SESSION_INPUTS = { + adapterType: kept("Hashed as adapter.adapterType."), + adapterConfig: kept("Hashed by content as adapterConfig."), + runtimeConfig: kept("Hashed by content as agentRuntimeConfig."), + defaultEnvironmentId: kept("Resolves to environment.selectedEnvironmentId, which is hashed."), + name: excluded(LIVE_AGENT_IDENTITY), + role: excluded(`${LIVE_AGENT_IDENTITY} Permission checks also read it per request.`), + title: excluded(LIVE_AGENT_IDENTITY), + capabilities: excluded(LIVE_AGENT_IDENTITY), + reportsTo: excluded(LIVE_AGENT_IDENTITY), + icon: excluded("Board display only."), + appearance: excluded("Board display only."), + budgetMonthlyCents: excluded("Budget admission runs before a run starts; it is not run input."), + metadata: excluded("No run preparation or native execution path reads agent metadata."), +} as const satisfies Record; + +export const PAPERCLIP_RUNNER_ADAPTER_CONFIG_SESSION_INPUTS = { + provider: kept("Selects the harness."), + model: kept("Selects the model."), + acpxAgent: kept("Selects the ACP agent."), + acpxSessionMode: kept("Cursor session mode."), + codexPermissionMode: kept("Codex approval policy, when Codex is the provider; dropped for another provider."), + opencodePermissionMode: kept("OpenCode tool permissions, when OpenCode is the provider; dropped for another provider."), + acpxPermissionMode: kept("ACP tool permissions, when ACPX is the provider; dropped for another provider."), + search: kept("Codex web search, when Codex is the provider; dropped for another provider."), + lifecycleMode: kept(`${NATIVE_LIFECYCLE} An explicit switch to warm also deliberately starts a new session.`), + idleTimeoutMs: kept(NATIVE_LIFECYCLE), + managedProfileId: kept("Managed agent profile."), + managedAgentsRetentionAcknowledged: kept("Managed agent retention terms."), + maxSessionListCostUsd: kept("Managed agent spend ceiling."), + agentCoreProfileId: kept("AgentCore profile."), + agentCoreRetentionAcknowledged: kept("AgentCore retention terms."), + maxEstimatedSessionCostUsd: kept("AgentCore spend ceiling."), + maxIterations: kept("AgentCore invocation limit."), + maxOutputTokens: kept("AgentCore invocation limit."), + timeoutSeconds: kept("AgentCore invocation limit."), + repoUrl: kept("Cursor Cloud repository."), + repoRef: kept("Cursor Cloud repository ref."), + prUrl: kept("Cursor Cloud pull request."), + cloudEnvName: kept("Cursor Cloud environment."), + workOnCurrentBranch: kept("Cursor Cloud branch policy."), + autoCreatePR: kept("Cursor Cloud pull request policy."), + skipReviewerRequest: kept("Cursor Cloud review policy."), + cwd: kept("Workspace location."), + instructionsFilePath: kept("Instructions; replaced by a content hash for managed bundles."), + env: kept("Process environment and secret bindings."), + workspaceStrategy: kept("Workspace strategy."), + workspaceRuntime: kept("Workspace runtime services."), + timeoutSec: excluded("Whole-turn time limit; the executor receives it apart from the native execution input."), + graceSec: excluded("Legacy child-process kill grace; the native runner path never reads it."), +} as const satisfies Record; + +export const ENVIRONMENT_CONFIG_SESSION_INPUTS = { + provider: kept("Sandbox provider."), + image: kept("Sandbox image."), + pluginKey: kept("Environment plugin."), + driverKey: kept("Environment plugin driver."), + driverConfig: kept("Plugin-owned driver configuration; every key under it is kept."), + runnerLifecycleMode: kept(`${NATIVE_LIFECYCLE} An explicit switch to warm also deliberately starts a new session.`), + runnerIdleTimeoutMs: kept(NATIVE_LIFECYCLE), + reuseLease: kept(`Decides whether a remote sandbox run defaults to warm. ${NATIVE_LIFECYCLE}`), + useHostAuth: kept("SSH authentication."), + tailscaleConnectionId: kept("SSH network path."), + tailscaleDeviceId: kept("SSH target machine."), + network: kept("SSH network path."), + tailscaleAuthKey: kept("SSH network credential."), + tailscaleAuthKeySecretRef: kept("SSH network credential."), + host: kept("SSH target machine."), + port: kept("SSH target machine."), + username: kept("SSH account."), + remoteWorkspacePath: kept("SSH workspace location."), + privateKey: kept("SSH credential."), + privateKeySecretRef: kept("SSH credential."), + knownHosts: kept("SSH host identity."), + strictHostKeyChecking: kept("SSH host identity policy."), + archiveOnRelease: excluded("What happens to a released sandbox; lease reuse decisions already ignore it."), + streamRunLogs: excluded("Host log streaming during a run."), + timeoutMs: excluded("Sandbox provider RPC timeout."), +} as const satisfies Record; + +export const AGENT_RUNTIME_CONFIG_SESSION_INPUTS = { + aiConnection: kept("Provider account and credentials."), + heartbeat: excluded("Wake scheduling, concurrency, daily caps, and max-turn continuation; none of it reaches the thread or the native execution input."), +} as const satisfies Record; + +export const SELECTED_ENVIRONMENT_SESSION_INPUTS = { + id: kept("A different environment is a different machine."), + driver: kept("Execution driver."), + config: kept("Hashed by key, as classified in ENVIRONMENT_CONFIG_SESSION_INPUTS."), + configRevisionAt: excluded( + "The row's update time. It moves on status, name, and description changes; the config is hashed by content.", + ), +} as const satisfies Record; + +export const ENVIRONMENT_SELECTION_SESSION_INPUTS = { + selectedEnvironmentId: kept("A different environment is a different machine."), + selectedEnvironment: kept("Hashed by field, as classified in SELECTED_ENVIRONMENT_SESSION_INPUTS."), + executionPolicy: kept("Execution policy."), + selectionSource: excluded("Records how the environment was chosen; nothing reads it to run."), +} as const satisfies Record; + +function excludedKeys(table: Record): Set { + return new Set(Object.entries(table).filter(([, value]) => value.kind === "excluded").map(([key]) => key)); +} + +const RUNNER_EXCLUDED_KEYS = excludedKeys(PAPERCLIP_RUNNER_ADAPTER_CONFIG_SESSION_INPUTS); +const ENVIRONMENT_CONFIG_EXCLUDED_KEYS = excludedKeys(ENVIRONMENT_CONFIG_SESSION_INPUTS); +const RUNTIME_CONFIG_EXCLUDED_KEYS = excludedKeys(AGENT_RUNTIME_CONFIG_SESSION_INPUTS); +const SELECTED_ENVIRONMENT_EXCLUDED_KEYS = excludedKeys(SELECTED_ENVIRONMENT_SESSION_INPUTS); +const ENVIRONMENT_SELECTION_EXCLUDED_KEYS = excludedKeys(ENVIRONMENT_SELECTION_SESSION_INPUTS); +const CODEX_ONLY_KEYS = ["search"] as const; + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function omitKeys(value: Record, keys: Iterable): Record { + const result = { ...value }; + for (const key of keys) delete result[key]; + return result; +} + +export function paperclipRunnerSessionAdapterConfig(config: Record): Record { + const result = omitKeys(config, RUNNER_EXCLUDED_KEYS); + const provider = config.provider ?? "codex"; + if (!isPaperclipRunnerProvider(provider)) return result; + const active = PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES[provider]; + const activeKey = active.configurable ? active.configKey : null; + const inactivePermissionKeys = Object.values(PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES) + .flatMap(capability => capability.configurable ? [capability.configKey] : []) + .filter(key => key !== activeKey); + return omitKeys(result, [...inactivePermissionKeys, ...(provider === "codex" ? [] : CODEX_ONLY_KEYS)]); +} + +export function sessionAgentRuntimeConfig(runtimeConfig: unknown): unknown { + return isRecord(runtimeConfig) ? omitKeys(runtimeConfig, RUNTIME_CONFIG_EXCLUDED_KEYS) : runtimeConfig; +} + +export function sessionEnvironment(environment: unknown): unknown { + if (!isRecord(environment)) return environment; + const result = omitKeys(environment, ENVIRONMENT_SELECTION_EXCLUDED_KEYS); + if (!isRecord(result.selectedEnvironment)) return result; + const selected = omitKeys(result.selectedEnvironment, SELECTED_ENVIRONMENT_EXCLUDED_KEYS); + if (isRecord(selected.config)) selected.config = omitKeys(selected.config, ENVIRONMENT_CONFIG_EXCLUDED_KEYS); + return { ...result, selectedEnvironment: selected }; +} diff --git a/server/src/services/heartbeat/session-preparation.ts b/server/src/services/heartbeat/session-preparation.ts index 9d7729f0954..b993f84c169 100644 --- a/server/src/services/heartbeat/session-preparation.ts +++ b/server/src/services/heartbeat/session-preparation.ts @@ -153,16 +153,14 @@ export async function prepareHeartbeatSession(db: Db, input: HeartbeatSessionPre : null, }; const sessionConfigMetadata = await buildEffectiveRunSessionConfigMetadata(sessionConfigMetadataInput); - const compatibleConfigMetadata: EffectiveRunSessionConfigMetadata[] = []; - const importedManagedInstructions = Boolean(taskSession && sessionConfigMetadataInput.managedInstructions?.contentHash - && readConfigFingerprintFromSessionParams(taskSession.sessionParamsJson)?.fingerprint !== sessionConfigMetadata.fingerprint); + const storedFingerprint = taskSession ? readConfigFingerprintFromSessionParams(taskSession.sessionParamsJson)?.fingerprint : undefined; + const storedFingerprintDiffers = Boolean(taskSession) && storedFingerprint !== sessionConfigMetadata.fingerprint; + const compatibleInputs: SessionMetadataInput[] = []; + const importedManagedInstructions = Boolean(storedFingerprintDiffers && sessionConfigMetadataInput.managedInstructions?.contentHash); if (importedManagedInstructions) { - compatibleConfigMetadata.push(await buildEffectiveRunSessionConfigMetadata({ - ...sessionConfigMetadataInput, retainManagedInstructionPaths: true, - })); + compatibleInputs.push({ ...sessionConfigMetadataInput, retainManagedInstructionPaths: true }); } - if (managedAiRuntime && aiBinding && taskSession && - readConfigFingerprintFromSessionParams(taskSession.sessionParamsJson)?.fingerprint !== sessionConfigMetadata.fingerprint) { + if (managedAiRuntime && aiBinding && taskSession && storedFingerprintDiffers) { const revisions = requestedAiBinding?.mode === "router" ? await db.select().from(agentConfigRevisions).where(and(eq(agentConfigRevisions.companyId, agent.companyId), eq(agentConfigRevisions.agentId, agent.id))).orderBy(desc(agentConfigRevisions.createdAt), desc(agentConfigRevisions.id)).limit(21) : []; @@ -174,13 +172,17 @@ export async function prepareHeartbeatSession(db: Db, input: HeartbeatSessionPre storedIdentity: taskSession.sessionParamsJson?.paperclipAiCredentialIdentity, sessionIdentity: managedAiRuntime.sessionIdentity, credentialIdentity: managedAiRuntime.identity, revisions, }); - compatibleConfigMetadata.push(...await Promise.all(candidates.flatMap(candidate => [ - buildEffectiveRunSessionConfigMetadata({ ...sessionConfigMetadataInput, ...candidate }), - ...(importedManagedInstructions ? [buildEffectiveRunSessionConfigMetadata({ - ...sessionConfigMetadataInput, ...candidate, retainManagedInstructionPaths: true, - })] : []), - ]))); + compatibleInputs.push(...candidates.flatMap(candidate => [ + { ...sessionConfigMetadataInput, ...candidate }, + ...(importedManagedInstructions ? [{ ...sessionConfigMetadataInput, ...candidate, retainManagedInstructionPaths: true }] : []), + ])); } + const legacyInputs = storedFingerprintDiffers + ? [sessionConfigMetadataInput, ...compatibleInputs].map(candidate => ({ ...candidate, legacyComposition: true })) + : []; + const compatibleConfigMetadata: EffectiveRunSessionConfigMetadata[] = await Promise.all( + [...compatibleInputs, ...legacyInputs].map(candidate => buildEffectiveRunSessionConfigMetadata(candidate)), + ); const configuredModel = readConfiguredModelFromAdapterConfig(runtimeConfig); if (context.refreshTools === true && agent.adapterType !== "paperclip_runner") { diff --git a/server/src/services/heartbeat/workspaces.ts b/server/src/services/heartbeat/workspaces.ts index 5e352f2b582..8f28452360e 100644 --- a/server/src/services/heartbeat/workspaces.ts +++ b/server/src/services/heartbeat/workspaces.ts @@ -16,6 +16,7 @@ import { sql } from "drizzle-orm"; import { materializeIsolatedTaskDirectory } from "../isolated-task-directory.js"; import { readConnectionFailure, type GitConnectionFailure } from "@paperclipai/adapter-utils/connection-failure"; import { managedAiSessionFingerprintConfig } from "../ai-connection-runtime.js"; +import { paperclipRunnerSessionAdapterConfig, sessionAgentRuntimeConfig, sessionEnvironment } from "./session-fingerprint-inputs.js"; import { PROJECT_REPOSITORIES_DIR, readGitWorkspaceSnapshot, @@ -2781,7 +2782,7 @@ async function resolveInstructionsConfigFingerprintMetadata( return metadata; } -function buildSessionConfigCategoryValues(input: { +export function buildSessionConfigCategoryValues(input: { adapterType: string; effectiveAdapterConfig: Record; agentRuntimeConfig: unknown; @@ -2796,6 +2797,7 @@ function buildSessionConfigCategoryValues(input: { runtimeSkills: unknown; agentConfigRevision: unknown; agentIdentityKeyId?: string; + legacyComposition?: boolean; }) { const sanitizedSecretManifest = sanitizeSecretManifestForConfigFingerprint( input.secretManifest, @@ -2818,18 +2820,21 @@ function buildSessionConfigCategoryValues(input: { const issueSettings = { ...parseObject(workspaceConfig.issueSettings) }; if (issueSettings.mode === workspaceConfig.requestedMode) delete issueSettings.mode; workspaceConfig.issueSettings = Object.keys(issueSettings).length ? issueSettings : null; + const legacy = input.legacyComposition === true; return { adapter: { adapterType: input.adapterType, ...(input.agentIdentityKeyId ? { agentIdentityKeyId: input.agentIdentityKeyId } : {}), - agentConfigRevision: input.agentConfigRevision, + ...(legacy ? { agentConfigRevision: input.agentConfigRevision } : {}), }, - adapterConfig: input.effectiveAdapterConfig, - agentRuntimeConfig: input.agentRuntimeConfig, + adapterConfig: legacy || input.adapterType !== "paperclip_runner" + ? input.effectiveAdapterConfig + : paperclipRunnerSessionAdapterConfig(input.effectiveAdapterConfig), + agentRuntimeConfig: legacy ? input.agentRuntimeConfig : sessionAgentRuntimeConfig(input.agentRuntimeConfig), instructions: input.instructions, issueOverrides: input.issueOverrides, workspaceConfig, - environment: input.environment, + environment: legacy ? input.environment : sessionEnvironment(input.environment), envBindings: { environment: { env: input.environmentEnv }, project: { env: input.projectEnv }, @@ -2857,6 +2862,7 @@ export async function buildEffectiveRunSessionConfigMetadata(input: { runtimeSkills: unknown; agentConfigRevision?: unknown; agentIdentityKeyId?: string; + legacyComposition?: boolean; }): Promise { const secretManifest = input.secretManifest ?? []; const instructions = input.managedInstructions ? { @@ -2902,6 +2908,7 @@ export async function buildEffectiveRunSessionConfigMetadata(input: { runtimeSkills: versionedSkills(input.runtimeSkills), agentConfigRevision: input.agentConfigRevision ?? null, agentIdentityKeyId: input.agentIdentityKeyId, + legacyComposition: input.legacyComposition, }); const fingerprints = createEffectiveRunConfigFingerprints({ session: categoryValues,