Skip to content

The open-source app everyone uses to manage agents at work

refactor(heartbeat): extract session preparation (#15966)

Dotta848e659bc666
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 79d71fb401..7cf3e8b147 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -1293,6 +1293,13 @@ cleanup. Public-path characterization tests are in
browser fixture also checks the persisted prompt variants and description revision
from a real process adapter before completing its task.
+Session preparation is in `server/src/services/heartbeat/session-preparation.ts`.
+It selects fresh or resumable sessions from effective config and managed-account
+identity, then resolves adapter session identity and compaction after workspace
+preparation. Both phases keep their original ordering in `heartbeat.ts`; they
+acquire no runtime resources. Public-path characterization tests live in
+`server/src/__tests__/heartbeat-session-preparation.test.ts`.
+
Run-log formatting is in `server/src/services/heartbeat/run-log.ts`. It bounds
stored event payloads, redacts and shortens log chunks, and caps stdout/stderr
excerpts. `heartbeat.ts` keeps event writes, current-user redaction, and live
diff --git a/server/src/__tests__/heartbeat-session-preparation.test.ts b/server/src/__tests__/heartbeat-session-preparation.test.ts
new file mode 100644
index 0000000000..7460a45733
--- /dev/null
+++ b/server/src/__tests__/heartbeat-session-preparation.test.ts
@@ -0,0 +1,114 @@
+import { randomUUID } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { agents, agentTaskSessions, companies, createDb, heartbeatRuns, issues } from "@paperclipai/db";
+import { registerServerAdapter, unregisterServerAdapter, type AdapterExecutionContext } from "../adapters/index.js";
+import { heartbeatService } from "../services/heartbeat.js";
+import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
+
+const support = await getEmbeddedPostgresTestSupport();
+const describePostgres = support.supported ? describe : describe.skip;
+if (!support.supported) console.warn(`Skipping session preparation tests: ${support.reason}`);
+
+describePostgres("heartbeat session preparation through adapter dispatch", () => {
+ const adapterType = "session_preparation_test";
+ const captured = new Map<string, AdapterExecutionContext>();
+ let temporary: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
+ let db: ReturnType<typeof createDb>;
+ let heartbeat: ReturnType<typeof heartbeatService>;
+
+ beforeAll(async () => {
+ temporary = await startEmbeddedPostgresTestDatabase("heartbeat-session-preparation-");
+ db = createDb(temporary.connectionString);
+ heartbeat = heartbeatService(db);
+ registerServerAdapter({
+ type: adapterType,
+ supportsLocalAgentJwt: false,
+ execute: async (input) => {
+ captured.set(input.runId, input);
+ // Settle the fixture's work so no automatic unfinished-task retry
+ // competes with the next explicit session-continuation wake.
+ await db.update(issues).set({ status: "in_review" }).where(eq(issues.id, String(input.context.issueId)));
+ return { exitCode: 0, signal: null, timedOut: false, sessionId: "saved-session", sessionParams: { sessionId: "saved-session", adapterState: "preserved" }, resultJson: {} };
+ },
+ testEnvironment: async () => ({ adapterType, status: "pass", checks: [], testedAt: new Date().toISOString() }),
+ });
+ }, 30_000);
+
+ afterAll(async () => {
+ await heartbeat?.drainActiveRunExecutions();
+ unregisterServerAdapter(adapterType);
+ await db?.$client.end({ timeout: 0 });
+ await temporary?.cleanup();
+ });
+
+ async function seed(runtimeConfig: Record<string, unknown> = {}) {
+ const companyId = randomUUID(), agentId = randomUUID(), issueId = randomUUID();
+ await db.insert(companies).values({ id: companyId, name: "Session fixture", issuePrefix: `S${companyId.slice(0, 6)}` });
+ await db.insert(agents).values({ id: agentId, companyId, name: "Session reader", adapterType, status: "idle", adapterConfig: { model: "model-a" }, runtimeConfig });
+ await db.insert(issues).values({ id: issueId, companyId, title: "Session fixture", status: "todo", assigneeAgentId: agentId, responsibleUserId: "session-user", issueNumber: 1 });
+ return { companyId, agentId, issueId };
+ }
+
+ async function execute(f: Awaited<ReturnType<typeof seed>>, context: Record<string, unknown> = {}) {
+ const run = await heartbeat.wakeup(f.agentId, {
+ source: "on_demand", triggerDetail: "manual", reason: "manual",
+ payload: { issueId: f.issueId }, contextSnapshot: { issueId: f.issueId, ...context },
+ });
+ expect(run).not.toBeNull();
+ await heartbeat.drainActiveRunExecutions();
+ const finished = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, run!.id)).then(rows => rows[0]);
+ expect(finished?.status, finished?.error ?? undefined).toBe("succeeded");
+ expect(captured.has(run!.id)).toBe(true);
+ return { input: captured.get(run!.id)!, finished };
+ }
+
+ it("reuses unchanged task sessions and strips host freshness metadata before dispatch", async () => {
+ const f = await seed();
+ const first = await execute(f);
+ expect(first.input.runtime.sessionId).toBeNull();
+ const stored = await db.select().from(agentTaskSessions).where(eq(agentTaskSessions.agentId, f.agentId)).then(rows => rows[0]);
+ expect(stored?.sessionParamsJson).toHaveProperty("__paperclipConfigFingerprint");
+ const resumed = await execute(f, { paperclipSessionHandoffMarkdown: "stale handoff", paperclipSessionRotationReason: "stale reason", paperclipPreviousSessionId: "stale session" });
+ expect(resumed.input.runtime).toMatchObject({ sessionId: "saved-session", sessionDisplayId: "saved-session", taskKey: f.issueId });
+ expect(resumed.input.runtime.sessionParams).toMatchObject({ sessionId: "saved-session", adapterState: "preserved" });
+ expect(resumed.input.runtime.sessionParams).not.toHaveProperty("__paperclipConfigFingerprint");
+ expect(resumed.input.context.paperclipSessionHandoffMarkdown).toBeUndefined();
+ expect(resumed.input.context.paperclipSessionRotationReason).toBeUndefined();
+ expect(resumed.input.context.paperclipPreviousSessionId).toBeUndefined();
+ expect(resumed.finished.sessionIdBefore).toBe("saved-session");
+ });
+
+ it("starts fresh when effective model configuration changes and persists the reason", async () => {
+ const f = await seed();
+ await execute(f);
+ await db.update(agents).set({ adapterConfig: { model: "model-b" } }).where(eq(agents.id, f.agentId));
+ const next = await execute(f);
+ expect(next.input.runtime.sessionId).toBeNull();
+ expect(next.input.runtime.sessionParams).toBeNull();
+ expect(next.finished.sessionIdBefore).toBeNull();
+ expect(next.finished.resultJson).toMatchObject({ configFreshness: { session: { reset: true, taskSessionAvailable: true, taskSessionReused: false } } });
+ });
+
+ it("refreshes tools with a fresh session when the selected adapter cannot refresh on resume", async () => {
+ const f = await seed();
+ await execute(f);
+ const next = await execute(f, { refreshTools: true });
+ expect(next.input.context.forceFreshSession).toBe(true);
+ expect(next.input.runtime.sessionId).toBeNull();
+ expect(next.finished.resultJson).toMatchObject({ configFreshness: { session: { resetReasons: ["forceFreshSession was requested"] } } });
+ });
+
+ it("rotates a session at the configured run threshold and supplies a handoff", async () => {
+ const f = await seed({ sessionCompaction: { enabled: true, maxSessionRuns: 1 } });
+ await execute(f);
+ await execute(f);
+ const next = await execute(f);
+ expect(next.input.runtime.sessionId).toBeNull();
+ expect(next.input.runtime.sessionParams).toBeNull();
+ expect(next.input.context.paperclipPreviousSessionId).toBe("saved-session");
+ expect(next.input.context.paperclipSessionRotationReason).toBe("session exceeded 1 runs");
+ expect(next.input.context.paperclipSessionHandoffMarkdown).toEqual(expect.any(String));
+ expect(next.finished.sessionIdBefore).toBeNull();
+ });
+});
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index bcbcdb0a64..03274998d8 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -1,3 +1,4 @@
+import { prepareHeartbeatSession, resolveHeartbeatAdapterSession } from "./heartbeat/session-preparation.js";
import { prepareHeartbeatTaskContext } from "./heartbeat/task-context.js";
import { selectHeartbeatEnvironment } from "./heartbeat/environment-selection.js";
import { prepareHeartbeatWorkspace } from "./heartbeat/workspace-preparation.js";
@@ -80,9 +81,6 @@ import {
normalizeResumeParamsForAdapter,
truncateDisplayId,
resolveLedgerScopeForRun,
- describeSessionResetReason,
- isCanonicalSessionIdForAdapter,
- requiresCanonicalSessionIds,
resolveNextSessionState,
resolveCacheAdjustedCostUsd,
resolveLedgerCostStatus,
@@ -139,16 +137,10 @@ export {
import {
buildExecutionWorkspaceConfigSnapshot,
stripWorkspaceRuntimeFromExecutionRunConfig,
- buildEffectiveRunSessionConfigMetadata,
- readConfigFingerprintFromSessionParams,
- readConfiguredModelFromAdapterConfig,
- resolveTaskSessionConfigFreshness,
- stripPaperclipSessionMetadataFromSessionParams,
resolveRuntimeSessionParamsForWorkspace,
buildRunWorkspaceHints,
buildReferencedProjectRunObservability,
assertGitSensitiveAdapterWorkspaceValid,
- type EffectiveRunSessionConfigMetadata,
createHeartbeatWorkspaceResolver,
} from "./heartbeat/workspaces.js";
export {
@@ -275,7 +267,7 @@ import {
} from "./ai-connection-runtime.js";
import { aiConnectionBindingSchema, aiRuntimeConnectionBindingSchema, type AiConnectionRouterSelection } from "@paperclipai/shared";
import { aiConnectionRouterService, AiConnectionPoolExhausted, applyAiConnectionRouterTaskSettings } from "./ai-connection-router.js";
-import { aiConnectionSessionCompatibilityInputs, managedAiSessionIdentityCompatible } from "./ai-connection-session.js";
+import { managedAiSessionIdentityCompatible } from "./ai-connection-session.js";
import {
getExecutionBlocker,
} from "./execution-blocker.js";
@@ -319,7 +311,6 @@ import {
} from "node:crypto";
import {
and,
- desc,
eq,
exists,
inArray,
@@ -336,7 +327,6 @@ import {
} from "@paperclipai/shared";
import {
agents,
- agentConfigRevisions,
agentWakeupRequests,
chatActions,
heartbeatRuns,
@@ -384,7 +374,6 @@ import {
type NativeExecutionInput,
type NativeSessionBackend,
} from "../vendor/paperclip-runner/index.js";
-import { createNativeSessionHandoffLoader } from "./native-runtime/native-session-handoff.js";
import { getRunLogStore, type RunLogHandle } from "./run-log-store.js";
import {
@@ -2910,143 +2899,22 @@ export function heartbeatService(
...identityRedactor.values,
...collectRunFailureSecretValues(runtimeConfig.env, secretKeys),
];
- const latestAgentConfigRevision = await getLatestAgentConfigRevision(
- agent.companyId,
- agent.id,
- );
- const sessionConfigMetadataInput = {
- agentIdentityKeyId: agentIdentity?.keyId,
- adapterType: agent.adapterType,
- effectiveAdapterConfig: runtimeConfig,
- managedAiHome: managedAiRuntime?.home,
- agentRuntimeConfig: agent.runtimeConfig,
- issueOverrides: issueAssigneeOverrides,
- workspaceConfig: {
- requestedMode: requestedExecutionWorkspaceMode,
- effectiveMode: effectiveExecutionWorkspaceMode,
- issueConfigRevisionAt:
- issueContext?.updatedAt instanceof Date
- ? issueContext.updatedAt.toISOString()
- : (issueContext?.updatedAt ?? null),
- projectConfigRevisionAt:
- projectContext?.updatedAt instanceof Date
- ? projectContext.updatedAt.toISOString()
- : (projectContext?.updatedAt ?? null),
- projectPolicy: projectExecutionWorkspacePolicy,
- issueSettings: issueExecutionWorkspaceSettings,
- reusableExecutionWorkspaceConfig:
- requestedReusableExecutionWorkspaceConfig,
- existingExecutionWorkspace: reusableExistingExecutionWorkspace
- ? {
- id: reusableExistingExecutionWorkspace.id,
- mode: reusableExistingExecutionWorkspace.mode,
- strategyType: reusableExistingExecutionWorkspace.strategyType,
- projectWorkspaceId:
- reusableExistingExecutionWorkspace.projectWorkspaceId,
- repoUrl: reusableExistingExecutionWorkspace.repoUrl,
- baseRef: reusableExistingExecutionWorkspace.baseRef,
- branchName: reusableExistingExecutionWorkspace.branchName,
- config: reusableExistingExecutionWorkspace.config,
- }
- : null,
- },
- environment: {
- selectionSource: environmentResolution.source,
- selectedEnvironmentId,
- selectedEnvironment: selectedEnvironmentForConfig
- ? {
- id: selectedEnvironmentForConfig.id,
- driver: selectedEnvironmentForConfig.driver,
- config: selectedEnvironmentForConfig.config,
- configRevisionAt:
- selectedEnvironmentForConfig.updatedAt instanceof Date
- ? selectedEnvironmentForConfig.updatedAt.toISOString()
- : (selectedEnvironmentForConfig.updatedAt ?? null),
- }
- : null,
- executionPolicy,
- },
- environmentEnv: selectedEnvironmentForConfig?.envVars ?? null,
- projectEnv: projectContext?.env ?? null,
- routineEnv: routineEnvContext.env,
- secretManifest,
- runtimeSkills: runtimeSkillEntries,
- agentConfigRevision: latestAgentConfigRevision
- ? {
- id: latestAgentConfigRevision.id,
- changedKeys: latestAgentConfigRevision.changedKeys,
- configRevisionAt:
- latestAgentConfigRevision.createdAt.toISOString(),
- }
- : null,
- };
- const sessionConfigMetadata = await buildEffectiveRunSessionConfigMetadata(sessionConfigMetadataInput);
- let compatibleConfigMetadata: EffectiveRunSessionConfigMetadata[] = [];
- if (managedAiRuntime && aiBinding && taskSession &&
- readConfigFingerprintFromSessionParams(taskSession.sessionParamsJson)?.fingerprint !== sessionConfigMetadata.fingerprint) {
- 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)
- : [];
- const candidates = aiConnectionSessionCompatibilityInputs({
- effectiveAdapterConfig: runtimeConfig, agentRuntimeConfig: agent.runtimeConfig,
- agentConfigRevision: sessionConfigMetadataInput.agentConfigRevision,
- issueOverrides: issueAssigneeOverrides, originalIssueOverrides: originalAiIssueOverrides,
- binding: aiBinding, router: requestedAiBinding?.mode === "router",
- storedIdentity: taskSession.sessionParamsJson?.paperclipAiCredentialIdentity,
- sessionIdentity: managedAiRuntime.sessionIdentity, credentialIdentity: managedAiRuntime.identity, revisions,
- });
- compatibleConfigMetadata = await Promise.all(candidates.map(candidate => buildEffectiveRunSessionConfigMetadata({ ...sessionConfigMetadataInput, ...candidate })));
- }
- const configuredModel =
- readConfiguredModelFromAdapterConfig(runtimeConfig);
- if (context.refreshTools === true && agent.adapterType !== "paperclip_runner") {
- const capability = getServerAdapter(agent.adapterType).supportsToolRefreshOnResume;
- const canRefresh = typeof capability === "function" ? capability(runtimeConfig) : capability === true;
- if (!canRefresh) context.forceFreshSession = true;
- }
- const wakeSessionResetReason = describeSessionResetReason(context);
- const sessionConfigFreshness = resolveTaskSessionConfigFreshness({
- hasTaskSession: taskSession != null,
- configuredModel,
- taskSessionParams:
- taskSession?.sessionParamsJson ?? taskSessionDecodedParams,
- configMetadata: sessionConfigMetadata,
- compatibleConfigMetadata,
- wakeResetReason: wakeSessionResetReason,
- preserveLegacySessionWithoutConfigMetadata:
- acceptedPlanContinuationWake && !acceptedPlanWakeRoutingDecision && !agentIdentity,
+ const preparedSession = await prepareHeartbeatSession(db, {
+ run, agent,
+ task: { context, issueRef, issueContext, projectContext, wakeCommentId, acceptedPlanContinuationWake, acceptedPlanWakeRoutingDecision },
+ session: { taskSession, taskSessionDecodedParams, explicitResumeSessionParams, explicitResumeSessionDisplayId, sessionCodec },
+ config: {
+ runtimeConfig, agentIdentity, issueAssigneeOverrides, originalAiIssueOverrides,
+ managedAiRuntime, aiBinding, requestedAiBinding, secretManifest, runtimeSkillEntries, routineEnvContext,
+ },
+ workspace: {
+ requestedExecutionWorkspaceMode, effectiveExecutionWorkspaceMode, projectExecutionWorkspacePolicy,
+ issueExecutionWorkspaceSettings, executionPolicy, requestedReusableExecutionWorkspaceConfig, reusableExistingExecutionWorkspace,
+ },
+ environment: { environmentResolution, selectedEnvironmentId, selectedEnvironmentForConfig },
+ getLatestAgentConfigRevision,
});
- const resetTaskSession =
- shouldResetTaskSessionForWake(context) || sessionConfigFreshness.reset;
- const sessionResetReason =
- sessionConfigFreshness.reasons.join("; ") || null;
- const taskSessionForRun = resetTaskSession ? null : taskSession;
- const getFreshSessionHandoff = issueRef ? createNativeSessionHandoffLoader({
- db, companyId: agent.companyId, issueId: issueRef.id, agentId: agent.id, before: run.createdAt,
- throughCommentId: readNonEmptyString(context.conversationReplayThroughCommentId) ?? (context.interactionKind ? null : wakeCommentId),
- }) : undefined;
- const previousSessionParams =
- explicitResumeSessionParams ??
- (isCanonicalSessionIdForAdapter(
- agent.adapterType,
- explicitResumeSessionDisplayId,
- )
- ? { sessionId: explicitResumeSessionDisplayId }
- : null) ??
- normalizeResumeParamsForAdapter(
- agent.adapterType,
- stripPaperclipSessionMetadataFromSessionParams(
- sessionCodec.deserialize(
- taskSessionForRun?.sessionParamsJson ?? null,
- ),
- ),
- );
- // Legacy plugins can consume the existing context field on a known-fresh
- // dispatch. Built-ins also load lazily if their resume attempt fails.
- if (agent.adapterType !== "paperclip_runner" && !previousSessionParams && getFreshSessionHandoff) {
- const handoff = await getFreshSessionHandoff();
- if (handoff) context.paperclipFreshSessionHandoffMarkdown = handoff;
- }
+ const { sessionConfigMetadata, configuredModel, resetTaskSession, sessionResetReason, taskSessionForRun, getFreshSessionHandoff, previousSessionParams } = preparedSession;
const {
resolvedWorkspace,
hostExecutionWorkspaceConfig,
@@ -3500,135 +3368,18 @@ export function heartbeatService(
) {
context.projectId = executionWorkspace.projectId;
}
- const runtimeSessionFallback =
- taskKey || resetTaskSession
- ? null
- : isCanonicalSessionIdForAdapter(agent.adapterType, runtime.sessionId)
- ? runtime.sessionId
- : null;
- const runtimeSessionDisplayId = truncateDisplayId(
- explicitResumeSessionDisplayId ??
- taskSessionForRun?.sessionDisplayId ??
- (sessionCodec.getDisplayId
- ? sessionCodec.getDisplayId(runtimeSessionParams)
- : null) ??
- readNonEmptyString(runtimeSessionParams?.sessionId) ??
- runtimeSessionFallback,
- );
- let previousSessionDisplayId = requiresCanonicalSessionIds(
- agent.adapterType,
- )
- ? truncateDisplayId(
- readNonEmptyString(previousSessionParams?.sessionId) ??
- (isCanonicalSessionIdForAdapter(
- agent.adapterType,
- runtimeSessionDisplayId,
- )
- ? runtimeSessionDisplayId
- : null) ??
- runtimeSessionFallback,
- )
- : runtimeSessionDisplayId;
- let runtimeSessionIdForAdapter =
- readNonEmptyString(runtimeSessionParams?.sessionId) ??
- runtimeSessionFallback;
- let runtimeSessionParamsForAdapter = normalizeSessionParams(
- stripPaperclipSessionMetadataFromSessionParams(runtimeSessionParams),
- );
-
- const sessionCompaction = await evaluateSessionCompaction({
+ const {
+ previousSessionDisplayId, runtimeSessionParamsForAdapter, taskSessionCredentialCompatible, runtimeForAdapter, configFreshnessResultMetadata, sessionCompaction,
+ } = await resolveHeartbeatAdapterSession({
agent,
- sessionId: previousSessionDisplayId ?? runtimeSessionIdForAdapter,
- issueId,
- continuationSummaryBody: continuationSummary?.body ?? null,
- });
- if (sessionCompaction.rotate) {
- context.paperclipSessionHandoffMarkdown =
- sessionCompaction.handoffMarkdown;
- context.paperclipSessionRotationReason = sessionCompaction.reason;
- context.paperclipPreviousSessionId =
- previousSessionDisplayId ?? runtimeSessionIdForAdapter;
- runtimeSessionIdForAdapter = null;
- runtimeSessionParamsForAdapter = null;
- previousSessionDisplayId = null;
- if (sessionCompaction.reason) {
- runtimeWorkspaceWarnings.push(
- `Starting a fresh session because ${sessionCompaction.reason}.`,
- );
- }
- } else {
- delete context.paperclipSessionHandoffMarkdown;
- delete context.paperclipSessionRotationReason;
- delete context.paperclipPreviousSessionId;
- }
-
- const taskSessionCredentialCompatible = !managedAiRuntime || managedAiSessionIdentityCompatible(
- taskSession?.sessionParamsJson?.paperclipAiCredentialIdentity,
- managedAiRuntime.sessionIdentity,
- managedAiRuntime.identity,
- );
- if (managedAiRuntime) {
- sessionConfigMetadata.aiCredentialIdentity = managedAiRuntime.sessionIdentity;
- if (!taskSessionCredentialCompatible) {
- runtimeSessionIdForAdapter = null;
- runtimeSessionParamsForAdapter = null;
- previousSessionDisplayId = null;
- delete executionContinuation?.resumeDelta;
- }
- }
- const runtimeForAdapter = {
- sessionId: runtimeSessionIdForAdapter,
- sessionParams: runtimeSessionParamsForAdapter,
- sessionDisplayId: previousSessionDisplayId,
- taskKey,
- };
- // A delta is safe only when the selected provider session is exactly the
- // task session whose last dispatch supplied the baseline history.
- if (
- executionContinuation?.resumeDelta &&
- (!taskSessionForRun ||
- !taskSession?.sessionDisplayId ||
- runtimeForAdapter.sessionDisplayId !== taskSession.sessionDisplayId ||
- resetTaskSession ||
- context.forceFreshSession === true)
- ) {
- delete executionContinuation.resumeDelta;
- }
- const configFreshnessResultMetadata = {
- version: sessionConfigMetadata.version,
- session: {
- fingerprintVersion: sessionConfigMetadata.version,
- categories: sessionConfigMetadata.categories,
- reset: resetTaskSession,
- resetReasons: sessionConfigFreshness.reasons,
- changedCategories: sessionConfigFreshness.changedCategories,
- taskSessionAvailable: taskSession != null,
- taskSessionReused: taskSessionForRun != null,
- storedFingerprintPresent: Boolean(
- sessionConfigFreshness.storedFingerprint,
- ),
- nextFingerprint: sessionConfigFreshness.nextFingerprint,
- },
+ task: { context, taskKey, issueId, continuationSummary, executionContinuation },
+ session: { runtime, taskSession, sessionCodec, explicitResumeSessionDisplayId, runtimeSessionParams, managedAiRuntime, prepared: preparedSession },
workspace: {
- fingerprintVersion: latestWorkspaceConfigMetadata.version,
- categories: latestWorkspaceConfigMetadata.categories,
- action: workspaceConfigFreshness.action,
- changedCategories: workspaceConfigFreshness.changedCategories,
- reasons: workspaceConfigFreshness.reasons,
- reuseRequested: requestedShouldReuseExisting,
- workspaceReused: Boolean(reusedExecutionWorkspace),
- configSnapshotRefreshed:
- resolvedWorkspaceReusePolicy.shouldRefreshWorkspaceConfigSnapshot,
- storedFingerprintPresent:
- workspaceConfigFreshness.storedFingerprintPresent,
- storedFingerprint: workspaceConfigFreshness.storedFingerprint,
- inferredFingerprint: workspaceConfigFreshness.inferredFingerprint,
- nextFingerprint: workspaceConfigFreshness.nextFingerprint,
- previousWorkspaceId:
- workspaceReuseRequest.requestedExecutionWorkspaceId,
- activeWorkspaceId: persistedExecutionWorkspace?.id ?? null,
+ latestWorkspaceConfigMetadata, workspaceConfigFreshness, reusedExecutionWorkspace, resolvedWorkspaceReusePolicy,
+ persistedExecutionWorkspace, runtimeWorkspaceWarnings, requestedShouldReuseExisting, workspaceReuseRequest,
},
- };
+ evaluateSessionCompaction,
+ });
let handle: RunLogHandle | null = null;
const goalCheckpointSession: {
diff --git a/server/src/services/heartbeat/session-preparation.ts b/server/src/services/heartbeat/session-preparation.ts
new file mode 100644
index 0000000000..a7845726dc
--- /dev/null
+++ b/server/src/services/heartbeat/session-preparation.ts
@@ -0,0 +1,385 @@
+import { and, desc, eq } from "drizzle-orm";
+import { agentConfigRevisions, type Db, type agents, type agentTaskSessions, type heartbeatRuns, type issues, type projects } from "@paperclipai/db";
+import type { AiConnectionBinding, AiRuntimeConnectionBinding } from "@paperclipai/shared";
+import { getServerAdapter } from "../../adapters/index.js";
+import type { prepareManagedAiRuntime } from "../ai-connection-runtime.js";
+import { aiConnectionSessionCompatibilityInputs, managedAiSessionIdentityCompatible } from "../ai-connection-session.js";
+import { createNativeSessionHandoffLoader } from "../native-runtime/native-session-handoff.js";
+import {
+ describeSessionResetReason, shouldResetTaskSessionForWake, isCanonicalSessionIdForAdapter,
+ normalizeResumeParamsForAdapter, normalizeSessionParams, requiresCanonicalSessionIds,
+ truncateDisplayId, type createHeartbeatRunState, type getAdapterSessionCodec,
+} from "./run-state.js";
+import {
+ buildEffectiveRunSessionConfigMetadata, readConfigFingerprintFromSessionParams,
+ readConfiguredModelFromAdapterConfig, resolveTaskSessionConfigFreshness,
+ stripPaperclipSessionMetadataFromSessionParams, type EffectiveRunSessionConfigMetadata,
+} from "./workspaces.js";
+import type { HeartbeatWorkspacePreparationInput, prepareHeartbeatWorkspace } from "./workspace-preparation.js";
+import type { prepareHeartbeatTaskContext } from "./task-context.js";
+
+type RunState = ReturnType<typeof createHeartbeatRunState>;
+type WorkspaceInput = HeartbeatWorkspacePreparationInput;
+type PreparedWorkspace = Awaited<ReturnType<typeof prepareHeartbeatWorkspace>>;
+type TaskContext = Awaited<ReturnType<typeof prepareHeartbeatTaskContext>>;
+type SessionMetadataInput = Parameters<typeof buildEffectiveRunSessionConfigMetadata>[0];
+type ManagedAiRuntime = Awaited<ReturnType<typeof prepareManagedAiRuntime>>;
+type TaskSession = typeof agentTaskSessions.$inferSelect | null;
+type SessionCodec = ReturnType<typeof getAdapterSessionCodec>;
+
+export interface HeartbeatSessionPreparationInput {
+ run: Pick<typeof heartbeatRuns.$inferSelect, "createdAt">;
+ agent: typeof agents.$inferSelect;
+ task: {
+ context: Record<string, unknown>;
+ issueRef: Pick<typeof issues.$inferSelect, "id"> | null;
+ issueContext: Pick<typeof issues.$inferSelect, "updatedAt"> | null;
+ projectContext: Pick<typeof projects.$inferSelect, "updatedAt" | "env"> | null;
+ wakeCommentId: string | null;
+ acceptedPlanContinuationWake: boolean;
+ acceptedPlanWakeRoutingDecision: unknown;
+ };
+ session: {
+ taskSession: TaskSession;
+ taskSessionDecodedParams: Record<string, unknown> | null;
+ explicitResumeSessionParams: Record<string, unknown> | null;
+ explicitResumeSessionDisplayId: string | null;
+ sessionCodec: SessionCodec;
+ };
+ config: {
+ runtimeConfig: Record<string, unknown>;
+ agentIdentity: { keyId: string } | undefined;
+ issueAssigneeOverrides: unknown;
+ originalAiIssueOverrides: unknown;
+ managedAiRuntime: ManagedAiRuntime | undefined;
+ aiBinding: AiConnectionBinding | undefined;
+ requestedAiBinding: AiRuntimeConnectionBinding | undefined;
+ secretManifest: SessionMetadataInput["secretManifest"];
+ runtimeSkillEntries: SessionMetadataInput["runtimeSkills"];
+ routineEnvContext: { env: unknown };
+ };
+ workspace: Pick<WorkspaceInput["policy"], "requestedExecutionWorkspaceMode" | "effectiveExecutionWorkspaceMode" | "projectExecutionWorkspacePolicy" | "issueExecutionWorkspaceSettings" | "executionPolicy"> & {
+ requestedReusableExecutionWorkspaceConfig: NonNullable<WorkspaceInput["reuse"]["reusableExistingExecutionWorkspace"]>["config"] | null;
+ reusableExistingExecutionWorkspace: WorkspaceInput["reuse"]["reusableExistingExecutionWorkspace"];
+ };
+ environment: Pick<WorkspaceInput["environment"], "environmentResolution" | "selectedEnvironmentId" | "selectedEnvironmentForConfig">;
+ getLatestAgentConfigRevision: RunState["getLatestAgentConfigRevision"];
+}
+
+function readNonEmptyString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+/** Selects a resumable session before workspace preparation; acquires no runtime resources. */
+export async function prepareHeartbeatSession(db: Db, input: HeartbeatSessionPreparationInput) {
+ const { run, agent, getLatestAgentConfigRevision } = input;
+ const { context, issueRef, issueContext, projectContext, wakeCommentId, acceptedPlanContinuationWake, acceptedPlanWakeRoutingDecision } = input.task;
+ const { taskSession, taskSessionDecodedParams, explicitResumeSessionParams, explicitResumeSessionDisplayId, sessionCodec } = input.session;
+ const { runtimeConfig, agentIdentity, issueAssigneeOverrides, originalAiIssueOverrides, managedAiRuntime, aiBinding, requestedAiBinding, secretManifest, runtimeSkillEntries, routineEnvContext } = input.config;
+ const { requestedExecutionWorkspaceMode, effectiveExecutionWorkspaceMode, projectExecutionWorkspacePolicy, issueExecutionWorkspaceSettings, executionPolicy, requestedReusableExecutionWorkspaceConfig, reusableExistingExecutionWorkspace } = input.workspace;
+ const { environmentResolution, selectedEnvironmentId, selectedEnvironmentForConfig } = input.environment;
+ const latestAgentConfigRevision = await getLatestAgentConfigRevision(
+ agent.companyId,
+ agent.id,
+ );
+ const sessionConfigMetadataInput = {
+ agentIdentityKeyId: agentIdentity?.keyId,
+ adapterType: agent.adapterType,
+ effectiveAdapterConfig: runtimeConfig,
+ managedAiHome: managedAiRuntime?.home,
+ agentRuntimeConfig: agent.runtimeConfig,
+ issueOverrides: issueAssigneeOverrides,
+ workspaceConfig: {
+ requestedMode: requestedExecutionWorkspaceMode,
+ effectiveMode: effectiveExecutionWorkspaceMode,
+ issueConfigRevisionAt:
+ issueContext?.updatedAt instanceof Date
+ ? issueContext.updatedAt.toISOString()
+ : (issueContext?.updatedAt ?? null),
+ projectConfigRevisionAt:
+ projectContext?.updatedAt instanceof Date
+ ? projectContext.updatedAt.toISOString()
+ : (projectContext?.updatedAt ?? null),
+ projectPolicy: projectExecutionWorkspacePolicy,
+ issueSettings: issueExecutionWorkspaceSettings,
+ reusableExecutionWorkspaceConfig:
+ requestedReusableExecutionWorkspaceConfig,
+ existingExecutionWorkspace: reusableExistingExecutionWorkspace
+ ? {
+ id: reusableExistingExecutionWorkspace.id,
+ mode: reusableExistingExecutionWorkspace.mode,
+ strategyType: reusableExistingExecutionWorkspace.strategyType,
+ projectWorkspaceId:
+ reusableExistingExecutionWorkspace.projectWorkspaceId,
+ repoUrl: reusableExistingExecutionWorkspace.repoUrl,
+ baseRef: reusableExistingExecutionWorkspace.baseRef,
+ branchName: reusableExistingExecutionWorkspace.branchName,
+ config: reusableExistingExecutionWorkspace.config,
+ }
+ : null,
+ },
+ environment: {
+ selectionSource: environmentResolution.source,
+ selectedEnvironmentId,
+ selectedEnvironment: selectedEnvironmentForConfig
+ ? {
+ id: selectedEnvironmentForConfig.id,
+ driver: selectedEnvironmentForConfig.driver,
+ config: selectedEnvironmentForConfig.config,
+ configRevisionAt:
+ selectedEnvironmentForConfig.updatedAt instanceof Date
+ ? selectedEnvironmentForConfig.updatedAt.toISOString()
+ : (selectedEnvironmentForConfig.updatedAt ?? null),
+ }
+ : null,
+ executionPolicy,
+ },
+ environmentEnv: selectedEnvironmentForConfig?.envVars ?? null,
+ projectEnv: projectContext?.env ?? null,
+ routineEnv: routineEnvContext.env,
+ secretManifest,
+ runtimeSkills: runtimeSkillEntries,
+ agentConfigRevision: latestAgentConfigRevision
+ ? {
+ id: latestAgentConfigRevision.id,
+ changedKeys: latestAgentConfigRevision.changedKeys,
+ configRevisionAt:
+ latestAgentConfigRevision.createdAt.toISOString(),
+ }
+ : null,
+ };
+ const sessionConfigMetadata = await buildEffectiveRunSessionConfigMetadata(sessionConfigMetadataInput);
+ let compatibleConfigMetadata: EffectiveRunSessionConfigMetadata[] = [];
+ if (managedAiRuntime && aiBinding && taskSession &&
+ readConfigFingerprintFromSessionParams(taskSession.sessionParamsJson)?.fingerprint !== sessionConfigMetadata.fingerprint) {
+ 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)
+ : [];
+ const candidates = aiConnectionSessionCompatibilityInputs({
+ effectiveAdapterConfig: runtimeConfig, agentRuntimeConfig: agent.runtimeConfig,
+ agentConfigRevision: sessionConfigMetadataInput.agentConfigRevision,
+ issueOverrides: issueAssigneeOverrides, originalIssueOverrides: originalAiIssueOverrides,
+ binding: aiBinding, router: requestedAiBinding?.mode === "router",
+ storedIdentity: taskSession.sessionParamsJson?.paperclipAiCredentialIdentity,
+ sessionIdentity: managedAiRuntime.sessionIdentity, credentialIdentity: managedAiRuntime.identity, revisions,
+ });
+ compatibleConfigMetadata = await Promise.all(candidates.map(candidate => buildEffectiveRunSessionConfigMetadata({ ...sessionConfigMetadataInput, ...candidate })));
+ }
+ const configuredModel =
+ readConfiguredModelFromAdapterConfig(runtimeConfig);
+ if (context.refreshTools === true && agent.adapterType !== "paperclip_runner") {
+ const capability = getServerAdapter(agent.adapterType).supportsToolRefreshOnResume;
+ const canRefresh = typeof capability === "function" ? capability(runtimeConfig) : capability === true;
+ if (!canRefresh) context.forceFreshSession = true;
+ }
+ const wakeSessionResetReason = describeSessionResetReason(context);
+ const sessionConfigFreshness = resolveTaskSessionConfigFreshness({
+ hasTaskSession: taskSession != null,
+ configuredModel,
+ taskSessionParams:
+ taskSession?.sessionParamsJson ?? taskSessionDecodedParams,
+ configMetadata: sessionConfigMetadata,
+ compatibleConfigMetadata,
+ wakeResetReason: wakeSessionResetReason,
+ preserveLegacySessionWithoutConfigMetadata:
+ acceptedPlanContinuationWake && !acceptedPlanWakeRoutingDecision && !agentIdentity,
+ });
+ const resetTaskSession =
+ shouldResetTaskSessionForWake(context) || sessionConfigFreshness.reset;
+ const sessionResetReason =
+ sessionConfigFreshness.reasons.join("; ") || null;
+ const taskSessionForRun = resetTaskSession ? null : taskSession;
+ const getFreshSessionHandoff = issueRef ? createNativeSessionHandoffLoader({
+ db, companyId: agent.companyId, issueId: issueRef.id, agentId: agent.id, before: run.createdAt,
+ throughCommentId: readNonEmptyString(context.conversationReplayThroughCommentId) ?? (context.interactionKind ? null : wakeCommentId),
+ }) : undefined;
+ const previousSessionParams =
+ explicitResumeSessionParams ??
+ (isCanonicalSessionIdForAdapter(
+ agent.adapterType,
+ explicitResumeSessionDisplayId,
+ )
+ ? { sessionId: explicitResumeSessionDisplayId }
+ : null) ??
+ normalizeResumeParamsForAdapter(
+ agent.adapterType,
+ stripPaperclipSessionMetadataFromSessionParams(
+ sessionCodec.deserialize(
+ taskSessionForRun?.sessionParamsJson ?? null,
+ ),
+ ),
+ );
+ // Legacy plugins can consume the existing context field on a known-fresh
+ // dispatch. Built-ins also load lazily if their resume attempt fails.
+ if (agent.adapterType !== "paperclip_runner" && !previousSessionParams && getFreshSessionHandoff) {
+ const handoff = await getFreshSessionHandoff();
+ if (handoff) context.paperclipFreshSessionHandoffMarkdown = handoff;
+ }
+ return { sessionConfigMetadata, configuredModel, sessionConfigFreshness, resetTaskSession, sessionResetReason, taskSessionForRun, getFreshSessionHandoff, previousSessionParams };
+}
+
+export interface HeartbeatAdapterSessionInput {
+ agent: typeof agents.$inferSelect;
+ task: {
+ context: Record<string, unknown>;
+ taskKey: string | null;
+ issueId: string | null;
+ continuationSummary: TaskContext["continuationSummary"];
+ executionContinuation: TaskContext["executionContinuation"];
+ };
+ session: {
+ runtime: { sessionId: string | null };
+ taskSession: TaskSession;
+ sessionCodec: SessionCodec;
+ explicitResumeSessionDisplayId: string | null;
+ runtimeSessionParams: Record<string, unknown> | null;
+ managedAiRuntime: ManagedAiRuntime | undefined;
+ prepared: Awaited<ReturnType<typeof prepareHeartbeatSession>>;
+ };
+ workspace: Pick<PreparedWorkspace, "latestWorkspaceConfigMetadata" | "workspaceConfigFreshness" | "reusedExecutionWorkspace" | "resolvedWorkspaceReusePolicy" | "persistedExecutionWorkspace"> & {
+ runtimeWorkspaceWarnings: string[];
+ requestedShouldReuseExisting: boolean;
+ workspaceReuseRequest: WorkspaceInput["reuse"]["workspaceReuseRequest"];
+ };
+ evaluateSessionCompaction: RunState["evaluateSessionCompaction"];
+}
+
+/** Resolves adapter identity after workspace preparation, retaining in-place context and delta updates. */
+export async function resolveHeartbeatAdapterSession(input: HeartbeatAdapterSessionInput) {
+ const { agent, evaluateSessionCompaction } = input;
+ const { context, taskKey, issueId, continuationSummary, executionContinuation } = input.task;
+ const { runtime, taskSession, sessionCodec, explicitResumeSessionDisplayId, runtimeSessionParams, managedAiRuntime, prepared } = input.session;
+ const { sessionConfigMetadata, sessionConfigFreshness, resetTaskSession, taskSessionForRun, previousSessionParams } = prepared;
+ const { latestWorkspaceConfigMetadata, workspaceConfigFreshness, reusedExecutionWorkspace, resolvedWorkspaceReusePolicy, persistedExecutionWorkspace, runtimeWorkspaceWarnings, requestedShouldReuseExisting, workspaceReuseRequest } = input.workspace;
+ const runtimeSessionFallback =
+ taskKey || resetTaskSession
+ ? null
+ : isCanonicalSessionIdForAdapter(agent.adapterType, runtime.sessionId)
+ ? runtime.sessionId
+ : null;
+ const runtimeSessionDisplayId = truncateDisplayId(
+ explicitResumeSessionDisplayId ??
+ taskSessionForRun?.sessionDisplayId ??
+ (sessionCodec.getDisplayId
+ ? sessionCodec.getDisplayId(runtimeSessionParams)
+ : null) ??
+ readNonEmptyString(runtimeSessionParams?.sessionId) ??
+ runtimeSessionFallback,
+ );
+ let previousSessionDisplayId = requiresCanonicalSessionIds(
+ agent.adapterType,
+ )
+ ? truncateDisplayId(
+ readNonEmptyString(previousSessionParams?.sessionId) ??
+ (isCanonicalSessionIdForAdapter(
+ agent.adapterType,
+ runtimeSessionDisplayId,
+ )
+ ? runtimeSessionDisplayId
+ : null) ??
+ runtimeSessionFallback,
+ )
+ : runtimeSessionDisplayId;
+ let runtimeSessionIdForAdapter =
+ readNonEmptyString(runtimeSessionParams?.sessionId) ??
+ runtimeSessionFallback;
+ let runtimeSessionParamsForAdapter = normalizeSessionParams(
+ stripPaperclipSessionMetadataFromSessionParams(runtimeSessionParams),
+ );
+
+ const sessionCompaction = await evaluateSessionCompaction({
+ agent,
+ sessionId: previousSessionDisplayId ?? runtimeSessionIdForAdapter,
+ issueId,
+ continuationSummaryBody: continuationSummary?.body ?? null,
+ });
+ if (sessionCompaction.rotate) {
+ context.paperclipSessionHandoffMarkdown =
+ sessionCompaction.handoffMarkdown;
+ context.paperclipSessionRotationReason = sessionCompaction.reason;
+ context.paperclipPreviousSessionId =
+ previousSessionDisplayId ?? runtimeSessionIdForAdapter;
+ runtimeSessionIdForAdapter = null;
+ runtimeSessionParamsForAdapter = null;
+ previousSessionDisplayId = null;
+ if (sessionCompaction.reason) {
+ runtimeWorkspaceWarnings.push(
+ `Starting a fresh session because ${sessionCompaction.reason}.`,
+ );
+ }
+ } else {
+ delete context.paperclipSessionHandoffMarkdown;
+ delete context.paperclipSessionRotationReason;
+ delete context.paperclipPreviousSessionId;
+ }
+
+ const taskSessionCredentialCompatible = !managedAiRuntime || managedAiSessionIdentityCompatible(
+ taskSession?.sessionParamsJson?.paperclipAiCredentialIdentity,
+ managedAiRuntime.sessionIdentity,
+ managedAiRuntime.identity,
+ );
+ if (managedAiRuntime) {
+ sessionConfigMetadata.aiCredentialIdentity = managedAiRuntime.sessionIdentity;
+ if (!taskSessionCredentialCompatible) {
+ runtimeSessionIdForAdapter = null;
+ runtimeSessionParamsForAdapter = null;
+ previousSessionDisplayId = null;
+ delete executionContinuation?.resumeDelta;
+ }
+ }
+ const runtimeForAdapter = {
+ sessionId: runtimeSessionIdForAdapter,
+ sessionParams: runtimeSessionParamsForAdapter,
+ sessionDisplayId: previousSessionDisplayId,
+ taskKey,
+ };
+ // A delta is safe only when the selected provider session is exactly the
+ // task session whose last dispatch supplied the baseline history.
+ if (
+ executionContinuation?.resumeDelta &&
+ (!taskSessionForRun ||
+ !taskSession?.sessionDisplayId ||
+ runtimeForAdapter.sessionDisplayId !== taskSession.sessionDisplayId ||
+ resetTaskSession ||
+ context.forceFreshSession === true)
+ ) {
+ delete executionContinuation.resumeDelta;
+ }
+ const configFreshnessResultMetadata = {
+ version: sessionConfigMetadata.version,
+ session: {
+ fingerprintVersion: sessionConfigMetadata.version,
+ categories: sessionConfigMetadata.categories,
+ reset: resetTaskSession,
+ resetReasons: sessionConfigFreshness.reasons,
+ changedCategories: sessionConfigFreshness.changedCategories,
+ taskSessionAvailable: taskSession != null,
+ taskSessionReused: taskSessionForRun != null,
+ storedFingerprintPresent: Boolean(
+ sessionConfigFreshness.storedFingerprint,
+ ),
+ nextFingerprint: sessionConfigFreshness.nextFingerprint,
+ },
+ workspace: {
+ fingerprintVersion: latestWorkspaceConfigMetadata.version,
+ categories: latestWorkspaceConfigMetadata.categories,
+ action: workspaceConfigFreshness.action,
+ changedCategories: workspaceConfigFreshness.changedCategories,
+ reasons: workspaceConfigFreshness.reasons,
+ reuseRequested: requestedShouldReuseExisting,
+ workspaceReused: Boolean(reusedExecutionWorkspace),
+ configSnapshotRefreshed:
+ resolvedWorkspaceReusePolicy.shouldRefreshWorkspaceConfigSnapshot,
+ storedFingerprintPresent:
+ workspaceConfigFreshness.storedFingerprintPresent,
+ storedFingerprint: workspaceConfigFreshness.storedFingerprint,
+ inferredFingerprint: workspaceConfigFreshness.inferredFingerprint,
+ nextFingerprint: workspaceConfigFreshness.nextFingerprint,
+ previousWorkspaceId:
+ workspaceReuseRequest.requestedExecutionWorkspaceId,
+ activeWorkspaceId: persistedExecutionWorkspace?.id ?? null,
+ },
+ };
+
+ return { previousSessionDisplayId, runtimeSessionParamsForAdapter, taskSessionCredentialCompatible, runtimeForAdapter, configFreshnessResultMetadata, sessionCompaction };
+}