The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
refactor(heartbeat): extract session preparation (#15966)
Dotta848e659bc666
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex 79d71fb401..7cf3e8b147 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -1293,6 +1293,13 @@ cleanup. Public-path characterization tests are inbrowser fixture also checks the persisted prompt variants and description revisionfrom 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 boundsstored event payloads, redacts and shortens log chunks, and caps stdout/stderrexcerpts. `heartbeat.ts` keeps event writes, current-user redaction, and livediff --git a/server/src/__tests__/heartbeat-session-preparation.test.ts b/server/src/__tests__/heartbeat-session-preparation.test.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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 };+}