mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 10:50:38 +09:00
Add local environment lifecycle (#4297)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Every heartbeat run needs a concrete place where the agent's adapter process executes. > - Today that execution location is implicitly the local machine, which makes it hard to track, audit, and manage as a first-class runtime concern. > - The first step is to represent the current local execution path explicitly without changing how users experience agent runs. > - This pull request adds core Environment and Environment Lease records, then routes existing local heartbeat execution through a default `Local` environment. > - The benefit is that local runs remain behavior-preserving while the system now has durable environment identity, lease lifecycle tracking, and activity records for execution placement. ## What Changed - Added `environments` and `environment_leases` database tables, schema exports, and migration `0065_environments.sql`. - Added shared environment constants, TypeScript types, and validators for environment drivers, statuses, lease policies, lease statuses, and cleanup states. - Added `environmentService` for listing, reading, creating, updating, and ensuring company-scoped environments. - Added environment lease lifecycle operations for acquire, metadata update, single-lease release, and run-wide release. - Updated heartbeat execution to lazily ensure a company-scoped default `Local` environment before adapter execution. - Updated heartbeat execution to acquire an ephemeral local environment lease, write `paperclipEnvironment` into the run context snapshot, and release active leases during run finalization. - Added activity log events for environment lease acquisition and release. - Added tests for environment service behavior and the local heartbeat environment lifecycle. - Added a CI-follow-up heartbeat guard so deferred issue comment wakes are promoted before automatic missing-comment retries, with focused batching test coverage. ## Verification Local verification run for this branch: - `pnpm -r typecheck` - `pnpm build` - `pnpm exec vitest run server/src/__tests__/environment-service.test.ts server/src/__tests__/heartbeat-local-environment.test.ts --pool=forks` Additional reviewer/CI verification: - Confirm `pnpm-lock.yaml` is not modified. - Confirm `pnpm test:run` passes in CI. - Confirm `PAPERCLIP_E2E_SKIP_LLM=true pnpm run test:e2e` passes in CI. - Confirm a local heartbeat run creates one active `Local` environment when needed, records one lease for the run, releases the lease when the run finishes, and includes `paperclipEnvironment` in the run context snapshot. Screenshots: not applicable; this PR has no UI changes. ## Risks - Migration risk: introduces two new tables and a new migration journal entry. Review should verify company scoping, indexes, foreign keys, and enum defaults are correct. - Lifecycle risk: heartbeat finalization now releases environment leases in addition to existing runtime cleanup. A finalization bug could leave stale active leases or mark a failed run's lease incorrectly. - Behavior-preservation risk: local adapter execution should remain unchanged apart from environment bookkeeping. Review should pay attention to the heartbeat path around context snapshot updates and final cleanup ordering. - Activity volume risk: each heartbeat run now logs lease acquisition and release events, increasing activity log volume by two records per run. ## Model Used OpenAI GPT-5.4 via Codex CLI. Capabilities used: repository inspection, TypeScript implementation review, local test/build execution, and PR-description drafting. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (N/A: no UI changes) - [x] I have updated relevant documentation to reflect my changes (N/A: no user-facing docs or commands changed) - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge
This commit is contained in:
Devin Foley
GitHub
parent
b69b563aa8
commit
13551b2bac
17 changed files with 1098 additions and 2 deletions
316
server/src/services/environments.ts
Normal file
316
server/src/services/environments.ts
Normal file
|
|
@ -0,0 +1,316 @@
|
|||
import { and, desc, eq } from "drizzle-orm";
|
||||
import type { Db } from "@paperclipai/db";
|
||||
import { environmentLeases, environments } from "@paperclipai/db";
|
||||
import {
|
||||
ENVIRONMENT_DRIVERS,
|
||||
ENVIRONMENT_LEASE_CLEANUP_STATUSES,
|
||||
ENVIRONMENT_LEASE_POLICIES,
|
||||
ENVIRONMENT_LEASE_STATUSES,
|
||||
ENVIRONMENT_STATUSES,
|
||||
type CreateEnvironment,
|
||||
type Environment,
|
||||
type EnvironmentLease,
|
||||
type EnvironmentLeaseCleanupStatus,
|
||||
type EnvironmentLeasePolicy,
|
||||
type EnvironmentLeaseStatus,
|
||||
type UpdateEnvironment,
|
||||
} from "@paperclipai/shared";
|
||||
|
||||
type EnvironmentRow = typeof environments.$inferSelect;
|
||||
type EnvironmentLeaseRow = typeof environmentLeases.$inferSelect;
|
||||
const DEFAULT_LOCAL_ENVIRONMENT_NAME = "Local";
|
||||
const DEFAULT_LOCAL_ENVIRONMENT_DESCRIPTION =
|
||||
"Default execution environment for Paperclip runs on this machine.";
|
||||
|
||||
function cloneRecord(value: unknown, fallback: Record<string, unknown> | null = null): Record<string, unknown> | null {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) return fallback;
|
||||
return { ...(value as Record<string, unknown>) };
|
||||
}
|
||||
|
||||
function readEnum<T extends string>(value: string | null, allowed: readonly T[], fieldName: string): T | null {
|
||||
if (value === null) return null;
|
||||
if ((allowed as readonly string[]).includes(value)) return value as T;
|
||||
throw new Error(`Unexpected ${fieldName} value: ${value}`);
|
||||
}
|
||||
|
||||
function toEnvironment(row: EnvironmentRow): Environment {
|
||||
return {
|
||||
id: row.id,
|
||||
companyId: row.companyId,
|
||||
name: row.name,
|
||||
description: row.description ?? null,
|
||||
driver: readEnum(row.driver, ENVIRONMENT_DRIVERS, "environment driver") ?? "local",
|
||||
status: readEnum(row.status, ENVIRONMENT_STATUSES, "environment status") ?? "active",
|
||||
config: cloneRecord(row.config, {}) ?? {},
|
||||
metadata: cloneRecord(row.metadata),
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
};
|
||||
}
|
||||
|
||||
function toEnvironmentLease(row: EnvironmentLeaseRow): EnvironmentLease {
|
||||
return {
|
||||
id: row.id,
|
||||
companyId: row.companyId,
|
||||
environmentId: row.environmentId,
|
||||
executionWorkspaceId: row.executionWorkspaceId ?? null,
|
||||
issueId: row.issueId ?? null,
|
||||
heartbeatRunId: row.heartbeatRunId ?? null,
|
||||
status: readEnum(row.status, ENVIRONMENT_LEASE_STATUSES, "environment lease status") ?? "active",
|
||||
leasePolicy: readEnum(row.leasePolicy, ENVIRONMENT_LEASE_POLICIES, "environment lease policy") ?? "ephemeral",
|
||||
provider: row.provider ?? null,
|
||||
providerLeaseId: row.providerLeaseId ?? null,
|
||||
acquiredAt: row.acquiredAt,
|
||||
lastUsedAt: row.lastUsedAt,
|
||||
expiresAt: row.expiresAt ?? null,
|
||||
releasedAt: row.releasedAt ?? null,
|
||||
failureReason: row.failureReason ?? null,
|
||||
cleanupStatus: readEnum(
|
||||
row.cleanupStatus,
|
||||
ENVIRONMENT_LEASE_CLEANUP_STATUSES,
|
||||
"environment lease cleanup status",
|
||||
),
|
||||
metadata: cloneRecord(row.metadata),
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
};
|
||||
}
|
||||
|
||||
export function environmentService(db: Db) {
|
||||
return {
|
||||
list: async (
|
||||
companyId: string,
|
||||
filters: {
|
||||
status?: string;
|
||||
driver?: string;
|
||||
} = {},
|
||||
): Promise<Environment[]> => {
|
||||
const conditions = [eq(environments.companyId, companyId)];
|
||||
if (filters.status) conditions.push(eq(environments.status, filters.status));
|
||||
if (filters.driver) conditions.push(eq(environments.driver, filters.driver));
|
||||
const rows = await db
|
||||
.select()
|
||||
.from(environments)
|
||||
.where(and(...conditions))
|
||||
.orderBy(desc(environments.updatedAt), desc(environments.createdAt));
|
||||
return rows.map(toEnvironment);
|
||||
},
|
||||
|
||||
getById: async (id: string): Promise<Environment | null> => {
|
||||
const row = await db.select().from(environments).where(eq(environments.id, id)).then((rows) => rows[0] ?? null);
|
||||
return row ? toEnvironment(row) : null;
|
||||
},
|
||||
|
||||
getLeaseById: async (id: string): Promise<EnvironmentLease | null> => {
|
||||
const row = await db
|
||||
.select()
|
||||
.from(environmentLeases)
|
||||
.where(eq(environmentLeases.id, id))
|
||||
.then((rows) => rows[0] ?? null);
|
||||
return row ? toEnvironmentLease(row) : null;
|
||||
},
|
||||
|
||||
ensureLocalEnvironment: async (companyId: string): Promise<Environment> => {
|
||||
const now = new Date();
|
||||
const row = await db
|
||||
.insert(environments)
|
||||
.values({
|
||||
companyId,
|
||||
name: DEFAULT_LOCAL_ENVIRONMENT_NAME,
|
||||
description: DEFAULT_LOCAL_ENVIRONMENT_DESCRIPTION,
|
||||
driver: "local",
|
||||
status: "active",
|
||||
config: {},
|
||||
metadata: {
|
||||
managedByPaperclip: true,
|
||||
defaultForCompany: true,
|
||||
},
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
})
|
||||
.onConflictDoNothing({
|
||||
target: [environments.companyId, environments.driver],
|
||||
})
|
||||
.returning()
|
||||
.then((rows) => rows[0] ?? null);
|
||||
if (row) return toEnvironment(row);
|
||||
|
||||
const existing = await db
|
||||
.select()
|
||||
.from(environments)
|
||||
.where(and(eq(environments.companyId, companyId), eq(environments.driver, "local")))
|
||||
.then((rows) => rows[0] ?? null);
|
||||
if (!existing) {
|
||||
throw new Error("Failed to ensure local environment");
|
||||
}
|
||||
return toEnvironment(existing);
|
||||
},
|
||||
|
||||
create: async (companyId: string, input: CreateEnvironment): Promise<Environment> => {
|
||||
const now = new Date();
|
||||
const row = await db
|
||||
.insert(environments)
|
||||
.values({
|
||||
companyId,
|
||||
name: input.name,
|
||||
description: input.description ?? null,
|
||||
driver: input.driver,
|
||||
status: input.status ?? "active",
|
||||
config: input.config ?? {},
|
||||
metadata: input.metadata ?? null,
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
})
|
||||
.returning()
|
||||
.then((rows) => rows[0] ?? null);
|
||||
if (!row) {
|
||||
throw new Error("Failed to create environment");
|
||||
}
|
||||
return toEnvironment(row);
|
||||
},
|
||||
|
||||
update: async (id: string, patch: UpdateEnvironment): Promise<Environment | null> => {
|
||||
const values: Partial<typeof environments.$inferInsert> = {
|
||||
updatedAt: new Date(),
|
||||
};
|
||||
if (patch.name !== undefined) values.name = patch.name;
|
||||
if (patch.description !== undefined) values.description = patch.description ?? null;
|
||||
if (patch.driver !== undefined) values.driver = patch.driver;
|
||||
if (patch.status !== undefined) values.status = patch.status;
|
||||
if (patch.config !== undefined) values.config = patch.config;
|
||||
if (patch.metadata !== undefined) values.metadata = patch.metadata ?? null;
|
||||
|
||||
const row = await db
|
||||
.update(environments)
|
||||
.set(values)
|
||||
.where(eq(environments.id, id))
|
||||
.returning()
|
||||
.then((rows) => rows[0] ?? null);
|
||||
return row ? toEnvironment(row) : null;
|
||||
},
|
||||
|
||||
listLeases: async (
|
||||
environmentId: string,
|
||||
filters: {
|
||||
status?: string;
|
||||
} = {},
|
||||
): Promise<EnvironmentLease[]> => {
|
||||
const conditions = [eq(environmentLeases.environmentId, environmentId)];
|
||||
if (filters.status) conditions.push(eq(environmentLeases.status, filters.status));
|
||||
const rows = await db
|
||||
.select()
|
||||
.from(environmentLeases)
|
||||
.where(and(...conditions))
|
||||
.orderBy(desc(environmentLeases.lastUsedAt), desc(environmentLeases.createdAt));
|
||||
return rows.map(toEnvironmentLease);
|
||||
},
|
||||
|
||||
acquireLease: async (input: {
|
||||
companyId: string;
|
||||
environmentId: string;
|
||||
executionWorkspaceId?: string | null;
|
||||
issueId?: string | null;
|
||||
heartbeatRunId?: string | null;
|
||||
leasePolicy?: EnvironmentLeasePolicy;
|
||||
provider?: string | null;
|
||||
providerLeaseId?: string | null;
|
||||
expiresAt?: Date | null;
|
||||
metadata?: Record<string, unknown> | null;
|
||||
}): Promise<EnvironmentLease> => {
|
||||
const now = new Date();
|
||||
const row = await db
|
||||
.insert(environmentLeases)
|
||||
.values({
|
||||
companyId: input.companyId,
|
||||
environmentId: input.environmentId,
|
||||
executionWorkspaceId: input.executionWorkspaceId ?? null,
|
||||
issueId: input.issueId ?? null,
|
||||
heartbeatRunId: input.heartbeatRunId ?? null,
|
||||
status: "active",
|
||||
leasePolicy: input.leasePolicy ?? "ephemeral",
|
||||
provider: input.provider ?? null,
|
||||
providerLeaseId: input.providerLeaseId ?? null,
|
||||
acquiredAt: now,
|
||||
lastUsedAt: now,
|
||||
expiresAt: input.expiresAt ?? null,
|
||||
releasedAt: null,
|
||||
failureReason: null,
|
||||
cleanupStatus: null,
|
||||
metadata: input.metadata ?? null,
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
})
|
||||
.returning()
|
||||
.then((rows) => rows[0] ?? null);
|
||||
if (!row) {
|
||||
throw new Error("Failed to acquire environment lease");
|
||||
}
|
||||
return toEnvironmentLease(row);
|
||||
},
|
||||
|
||||
releaseLease: async (
|
||||
id: string,
|
||||
status: Extract<EnvironmentLeaseStatus, "released" | "expired" | "failed"> = "released",
|
||||
options?: {
|
||||
failureReason?: string;
|
||||
cleanupStatus?: EnvironmentLeaseCleanupStatus;
|
||||
},
|
||||
) => {
|
||||
const now = new Date();
|
||||
const row = await db
|
||||
.update(environmentLeases)
|
||||
.set({
|
||||
status,
|
||||
releasedAt: now,
|
||||
lastUsedAt: now,
|
||||
updatedAt: now,
|
||||
...(options?.failureReason !== undefined ? { failureReason: options.failureReason } : {}),
|
||||
...(options?.cleanupStatus !== undefined ? { cleanupStatus: options.cleanupStatus } : {}),
|
||||
})
|
||||
.where(eq(environmentLeases.id, id))
|
||||
.returning()
|
||||
.then((rows) => rows[0] ?? null);
|
||||
return row ? toEnvironmentLease(row) : null;
|
||||
},
|
||||
|
||||
updateLeaseMetadata: async (
|
||||
id: string,
|
||||
metadata: Record<string, unknown> | null,
|
||||
): Promise<EnvironmentLease | null> => {
|
||||
const row = await db
|
||||
.update(environmentLeases)
|
||||
.set({
|
||||
metadata,
|
||||
lastUsedAt: new Date(),
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(eq(environmentLeases.id, id))
|
||||
.returning()
|
||||
.then((rows) => rows[0] ?? null);
|
||||
return row ? toEnvironmentLease(row) : null;
|
||||
},
|
||||
|
||||
releaseLeasesForRun: async (
|
||||
heartbeatRunId: string,
|
||||
status: Extract<EnvironmentLeaseStatus, "released" | "expired" | "failed"> = "released",
|
||||
): Promise<EnvironmentLease[]> => {
|
||||
const now = new Date();
|
||||
const rows = await db
|
||||
.update(environmentLeases)
|
||||
.set({
|
||||
status,
|
||||
releasedAt: now,
|
||||
lastUsedAt: now,
|
||||
updatedAt: now,
|
||||
})
|
||||
.where(
|
||||
and(
|
||||
eq(environmentLeases.heartbeatRunId, heartbeatRunId),
|
||||
eq(environmentLeases.status, "active"),
|
||||
),
|
||||
)
|
||||
.returning();
|
||||
return rows.map(toEnvironmentLease);
|
||||
},
|
||||
};
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue