mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Durable agent files live in object storage. Each server keeps a local copy (the projection), marked with the head generation it matches > - When the projection is stale, the next locked read or write restores it: it downloads every file from object storage. This happens for the first run of each agent on a new server (every deploy on hosted ephemeral servers) and after another server wrote > - The download ran inside the transaction that holds the `agents` row lock (`FOR UPDATE`), on the main pool for the run-start read (`readCommittedForRuntime`) and on the 2-connection file-storage pool for the store. A download can take up to 30 s > - After a deploy at 1,000 agents, this is one long row lock and one pinned connection per agent, all at once, and every writer of that agent waits behind it > - This pull request downloads the files outside the transaction and takes the lock again only to swap them in > - The benefit is that the row lock is held for milliseconds instead of the download time (0 ms observed instead of 321 ms with a 300 ms download in the test), and writers do not wait for a download ## Linked Issues or Issue Description **What existing behavior does this improve?** The restore of a stale local copy of an agent's durable files (the first run of each agent on a new server, or after another server wrote). **Subsystem affected** Server: durable agent files (`agent-file-durability.ts`, `agent-file-store.ts`, `agent-instruction-revisions.ts`). **Current behavior** The restore downloads every file from object storage inside the transaction that holds the `agents` row lock (`FOR UPDATE`) and a pooled connection. A download can take up to 30 s, and every writer of that agent waits behind it. **Proposed behavior** Under the lock, detect that a download is needed and roll back. Download the head's files, verified by digest, into a private staging directory with no lock. Run the transaction again, and swap the staged files in only when the head generation is unchanged. After two changed heads, restore under the lock as before. **Reason and benefit** After a deploy at 1,000 agents, every agent's first run restores at once. The row lock and connection are now held for milliseconds instead of the download time, and writers do not wait for a download. **Additional context** Refs the 1,000-concurrent-agents plan (`doc/plans/2026-11-13-thousand-concurrent-agents.md`). The save path had the same problem for uploads and was fixed earlier with uploads before the lock (`uploadAgentFilesBeforeCommit`); this is the restore side. Reading the head before every transaction was considered; it adds a query to every call, while the deferral costs nothing when the projection is current. ## What Changed - `agent-file-durability.ts`: the download loop moves into `downloadAgentFiles`, unchanged. `withAgentFilesRestoredBeforeLock(work)` runs `work` in a scope. Inside the scope, the first restore of an attempt that needs a download throws a private deferral error, which rolls back the transaction. The wrapper stages the download in `.agent-files-<uuid>` next to the root and runs `work` again. `restoreDurableAgentFiles` uses a staged directory only when its generation equals the head it reads under the lock. Staged directories are removed when the scope ends. - Only the first restore of each attempt can defer, so nested restores of other agents keep their old behavior. Outside the scope, the behavior is unchanged. - `agent-file-store.ts` (`locked`, so every store read, write, apply and working-copy preparation) and `agent-instruction-revisions.ts` (`readCommittedForRuntime`, `readCurrent`, `materializeCurrent`) run their transactions in the scope. ## Verification - New test `server/src/__tests__/agent-file-restore-locking.test.ts` on embedded PostgreSQL, with an object-storage fixture: - Hold time, with a 300 ms download, through `readCommittedForRuntime` (the run-start read). Before: the download ran with the agent row locked, and the row was locked 321 ms of 322 ms. After: the download ran with the row unlocked, and a sampler saw the row locked for 0 ms. - Concurrency: a board write of the same file runs while the reader's download is blocked. Before: the writer waited for the reader's download (5 s timeout). After: the writer commits a new head during the download. The reader then discards its stale staged copy and returns the writer's content. The projection is marked at the writer's generation, and no staging directory is left. - Failure: when object storage fails, the read fails once with the storage error, after one attempt made without the row lock, and leaves no staging directory. - Progress: when the head generation changes during each of two downloads, the third attempt restores under the lock as before (3 downloads), and the projection matches the final head. - `npx vitest run` for agent-file-checkpoint-locking, agent-file-checkpoints, agent-file-durability, agent-file-restore-locking, agent-instruction-revisions, agent-instruction-working-copies, agent-instructions-service, agent-directory-working-copies and agent-instructions-routes: 287 passed, 1 skipped. - `npx tsc --noEmit -p server/tsconfig.json`: passes. ## Risks - A deferred attempt runs the transaction body again. The deferral happens at the first restore, before the body writes files, and the transaction rollback undoes database work, so the second attempt starts from the same state. - A staged download uses disk next to the agent root until the scope ends, the same as the temporary directory of the old download. - If the head changes during every download, the third attempt downloads under the lock as before. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
449 lines
20 KiB
TypeScript
449 lines
20 KiB
TypeScript
import { currentPluginInteractionOrigin } from "./plugin-interaction-context.js";
|
|
import { extractAgentMentionIds } from "@paperclipai/shared";
|
|
import { assertAgentInteraction } from "./agent-interaction-policy.js";
|
|
import { updateAgentConfigurationInTransaction } from "./agent-configuration-transaction.js";
|
|
import { createHash } from "node:crypto";
|
|
import { adoptAgentFiles, agentFileToken, isAgentFileSaveRecorded } from "./agent-file-store.js";
|
|
import { withAgentFilesRestoredBeforeLock } from "./agent-file-durability.js";
|
|
import { invalidateAgentFileProjection, persistDurableAgentFiles } from "./agent-file-durability.js";
|
|
import { and, desc, eq, getTableColumns, lt, or, sql } from "drizzle-orm";
|
|
import {
|
|
activityLog,
|
|
agents,
|
|
plugins,
|
|
pluginManagedResources,
|
|
agentInstructionHeads as heads,
|
|
agentInstructionRevisions as revisions,
|
|
fileStorageDb,
|
|
type Db,
|
|
} from "@paperclipai/db";
|
|
import type {
|
|
AgentInstructionCommitReceipt,
|
|
AgentInstructionDiff,
|
|
AgentInstructionHistory,
|
|
AgentInstructionSnapshot,
|
|
AgentInstructionSource,
|
|
} from "@paperclipai/shared";
|
|
import { conflict, forbidden, notFound, unprocessable } from "../errors.js";
|
|
import {
|
|
agentInstructionsBundleMode,
|
|
deriveBundleState,
|
|
resolveManagedInstructionsRoot,
|
|
} from "./agent-instructions.js";
|
|
import {
|
|
instructionBytes,
|
|
instructionPath,
|
|
assertInstructionPathSafe,
|
|
readInstructionBytes,
|
|
materializeInstructionBytes,
|
|
} from "./agent-instruction-files.js";
|
|
import {
|
|
authorizeInstructionCommit,
|
|
authorizeInstructionRead,
|
|
} from "./agent-instruction-authorization.js";
|
|
import type { AuthorizationActor } from "./authorization.js";
|
|
|
|
type Tx = Parameters<Parameters<Db["transaction"]>[0]>[0];
|
|
type Revision = typeof revisions.$inferSelect;
|
|
type PluginResetActor = { type: "plugin"; pluginId: string; pluginKey: string; agentKey: string };
|
|
type RevisionActor = AuthorizationActor | PluginResetActor;
|
|
const { contentBase64: _contentColumn, ...revisionMetadataColumns } =
|
|
getTableColumns(revisions);
|
|
export type InstructionTarget = { companyId: string; agentId: string };
|
|
export type InstructionCommitInput = InstructionTarget & {
|
|
entryFile: string;
|
|
content: string | Uint8Array;
|
|
baseRevisionId: string | null;
|
|
source: Exclude<AgentInstructionSource, "seed" | "restore">;
|
|
};
|
|
function metadata(row: Omit<Revision, "contentBase64">) {
|
|
const { createdAt, source, ...fields } = row;
|
|
return {
|
|
...fields,
|
|
source: source as AgentInstructionSource,
|
|
createdAt: createdAt.toISOString(),
|
|
};
|
|
}
|
|
function snapshot(row: Revision): AgentInstructionSnapshot {
|
|
const { contentBase64, ...fields } = row;
|
|
return {
|
|
revision: metadata(fields),
|
|
content: Buffer.from(contentBase64, "base64").toString("utf8"),
|
|
};
|
|
}
|
|
function owner(target: InstructionTarget, entryFile: string) {
|
|
return and(
|
|
eq(revisions.companyId, target.companyId),
|
|
eq(revisions.agentId, target.agentId),
|
|
eq(revisions.entryFile, entryFile),
|
|
);
|
|
}
|
|
function headOwner(target: InstructionTarget, entryFile: string) {
|
|
return and(
|
|
eq(heads.companyId, target.companyId),
|
|
eq(heads.agentId, target.agentId),
|
|
eq(heads.entryFile, entryFile),
|
|
);
|
|
}
|
|
|
|
export function agentInstructionRevisionService(db: Db) {
|
|
db = fileStorageDb(db);
|
|
async function lockTarget(
|
|
tx: Tx,
|
|
target: InstructionTarget,
|
|
actor?: AuthorizationActor,
|
|
) {
|
|
if (actor?.type === "agent" && actor.companyId !== target.companyId)
|
|
throw notFound("Agent not found");
|
|
const [agent] = await tx
|
|
.select()
|
|
.from(agents)
|
|
.where(
|
|
and(
|
|
eq(agents.id, target.agentId),
|
|
eq(agents.companyId, target.companyId),
|
|
),
|
|
)
|
|
.for("update");
|
|
if (!agent) throw notFound("Agent not found");
|
|
if (agentInstructionsBundleMode(agent) === "external") {
|
|
throw unprocessable(
|
|
"External host instructions do not support revision write-back. Ask an instance administrator to migrate this bundle to managed storage.",
|
|
{ code: "INSTRUCTION_MANAGED_BUNDLE_REQUIRED" },
|
|
);
|
|
}
|
|
const state = deriveBundleState(agent);
|
|
const entryFile = instructionPath(state.entryFile);
|
|
return { agent, entryFile, root: resolveManagedInstructionsRoot(agent) };
|
|
}
|
|
async function authorizeRead(
|
|
tx: Tx,
|
|
actor: AuthorizationActor,
|
|
target: InstructionTarget,
|
|
) {
|
|
return authorizeInstructionRead(tx, actor, { companyId: target.companyId, id: target.agentId });
|
|
}
|
|
// Trusted host-only reset authority. No HTTP or agent tool accepts this actor.
|
|
async function authorizePluginReset(tx: Tx, actor: PluginResetActor, target: InstructionTarget, agent: typeof agents.$inferSelect) {
|
|
const [plugin] = await tx.select().from(plugins).where(and(eq(plugins.id, actor.pluginId), eq(plugins.pluginKey, actor.pluginKey)));
|
|
const marker = agent.metadata?.paperclipManagedResource as Record<string, unknown> | undefined;
|
|
const [binding] = await tx.select().from(pluginManagedResources).where(and(
|
|
eq(pluginManagedResources.pluginId, actor.pluginId), eq(pluginManagedResources.pluginKey, actor.pluginKey),
|
|
eq(pluginManagedResources.companyId, target.companyId), eq(pluginManagedResources.resourceKind, "agent"),
|
|
eq(pluginManagedResources.resourceKey, actor.agentKey), eq(pluginManagedResources.resourceId, target.agentId),
|
|
));
|
|
if (!plugin || plugin.status !== "ready" || !plugin.manifestJson.capabilities.includes("agents.managed")
|
|
|| !plugin.manifestJson.agents?.some((declaration) => declaration.agentKey === actor.agentKey)
|
|
|| !binding || marker?.pluginId !== actor.pluginId || marker.pluginKey !== actor.pluginKey
|
|
|| marker.resourceKind !== "agent" || marker.resourceKey !== actor.agentKey) {
|
|
throw forbidden("Plugin reset is limited to its declared, bound managed agent");
|
|
}
|
|
const declared = plugin.manifestJson.agents!.find((declaration) => declaration.agentKey === actor.agentKey)!;
|
|
return { ...actor, declaredEntryFile: instructionPath(declared.instructions?.entryFile ?? "AGENTS.md") };
|
|
}
|
|
async function readForPluginReset(target: InstructionTarget, actor: PluginResetActor) {
|
|
return db.transaction(async (tx) => {
|
|
const state = await lockTarget(tx, target);
|
|
const bound = await authorizePluginReset(tx, actor, target, state.agent);
|
|
// Preserve the formerly configured entry before an explicit stock reset.
|
|
await currentFile(tx, target, state, bound);
|
|
const row = await currentFile(tx, target, { ...state, entryFile: bound.declaredEntryFile }, bound);
|
|
return { snapshot: row ? snapshot(row) : null, configuredEntryFile: state.entryFile };
|
|
});
|
|
}
|
|
async function head(tx: Tx, target: InstructionTarget, entryFile: string) {
|
|
const [result] = await tx
|
|
.select({ revision: revisions })
|
|
.from(heads)
|
|
.innerJoin(revisions, eq(revisions.id, heads.revisionId))
|
|
.where(headOwner(target, entryFile));
|
|
return result?.revision ?? null;
|
|
}
|
|
// The deployed revision tables are read-only upgrade input. Current bytes
|
|
// live in the agent directory; old UUID clients receive a content ETag.
|
|
async function currentFile(tx: Tx, target: InstructionTarget, state: Awaited<ReturnType<typeof lockTarget>>, actor?: RevisionActor) {
|
|
await adoptAgentFiles(tx, state.agent);
|
|
const bytes = await readInstructionBytes(state.root, state.entryFile);
|
|
if (bytes === null) return null;
|
|
return currentRow(target, state.entryFile, bytes, actor);
|
|
}
|
|
function currentRow(target: InstructionTarget, entryFile: string, bytes: Buffer, actor?: RevisionActor): Revision {
|
|
const origin = currentPluginInteractionOrigin();
|
|
return { ...target, id: agentFileToken(bytes), entryFile, contentBase64: bytes.toString("base64"),
|
|
contentHash: createHash("sha256").update(bytes).digest("hex"), byteLength: bytes.length,
|
|
parentRevisionId: null, baseRevisionId: null, restoredFromRevisionId: null, source: "api",
|
|
actorAgentId: origin?.agentId ?? (actor?.type === "agent" ? actor.agentId ?? null : null),
|
|
actorUserId: origin ? null : actor?.type === "board" ? actor.userId ?? null : null,
|
|
responsibleUserId: origin ? null : actor?.type === "board" ? actor.userId ?? null : actor?.type === "agent" ? actor.onBehalfOfUserId ?? null : null,
|
|
sourceRunId: origin ? origin.runId ?? null : actor && actor.type !== "plugin" ? actor.runId ?? null : null, createdAt: new Date(0) };
|
|
}
|
|
async function getRevision(
|
|
tx: Tx,
|
|
target: InstructionTarget,
|
|
entryFile: string,
|
|
id: string,
|
|
) {
|
|
const [row] = await tx
|
|
.select()
|
|
.from(revisions)
|
|
.where(and(owner(target, entryFile), eq(revisions.id, id)));
|
|
if (!row) throw notFound("Instruction revision not found");
|
|
return row;
|
|
}
|
|
async function readCurrent(
|
|
target: InstructionTarget,
|
|
actor: AuthorizationActor,
|
|
): Promise<AgentInstructionSnapshot | null> {
|
|
return withAgentFilesRestoredBeforeLock(() => db.transaction(async (tx) => {
|
|
const state = await lockTarget(tx, target, actor);
|
|
const bound = await authorizeRead(tx, actor, target);
|
|
const row = await currentFile(tx, target, state, bound);
|
|
return row ? snapshot(row) : null;
|
|
}));
|
|
}
|
|
/** Trusted orchestration read for the already authorized run target. This
|
|
* never seeds or writes, and is not exposed through HTTP or model tools. */
|
|
async function readCommittedForRuntime(target: InstructionTarget): Promise<AgentInstructionSnapshot | null> {
|
|
return withAgentFilesRestoredBeforeLock(() => db.transaction(async (tx) => {
|
|
const state = await lockTarget(tx, target);
|
|
const current = await currentFile(tx, target, state);
|
|
return current ? snapshot(current) : null;
|
|
}));
|
|
}
|
|
/** Rebuild disk from the current committed head under the same lock as commits. Safe after restart. */
|
|
async function materializeCurrent(target: InstructionTarget): Promise<void> {
|
|
await withAgentFilesRestoredBeforeLock(() => db.transaction(async (tx) => {
|
|
const state = await lockTarget(tx, target);
|
|
await adoptAgentFiles(tx, state.agent);
|
|
}));
|
|
}
|
|
async function commitInternal(
|
|
input:
|
|
| InstructionCommitInput
|
|
| (Omit<InstructionCommitInput, "content" | "source"> & {
|
|
restoreRevisionId: string;
|
|
}),
|
|
actor: RevisionActor,
|
|
configuredEntryFile?: string,
|
|
): Promise<AgentInstructionCommitReceipt> {
|
|
instructionPath(input.entryFile);
|
|
const bytes = "content" in input ? instructionBytes(input.content) : null;
|
|
const result = await db.transaction(async (tx) => {
|
|
const restoredInput = "restoreRevisionId" in input
|
|
? await getRevision(tx, input, input.entryFile, input.restoreRevisionId) : null;
|
|
const submittedContent = (bytes ?? Buffer.from(restoredInput!.contentBase64, "base64")).toString("utf8");
|
|
await assertAgentInteraction(tx, { companyId: input.companyId, actorAgentId: actor.type === "agent" ? actor.agentId : null,
|
|
operation: "configure", targetAgentId: input.agentId, lockAgentIds: extractAgentMentionIds(submittedContent), lock: "update" });
|
|
const state = await lockTarget(tx, input, actor.type === "plugin" ? undefined : actor);
|
|
const bound = actor.type === "plugin"
|
|
? await authorizePluginReset(tx, actor, input, state.agent)
|
|
: await authorizeInstructionCommit(tx, actor, state.agent);
|
|
if (bound.type === "plugin") {
|
|
if (input.entryFile !== bound.declaredEntryFile) throw forbidden("Plugin reset must restore its declared entry file");
|
|
if (configuredEntryFile !== state.entryFile) throw conflict("Configured instruction entry changed; read the current entry and retry", { code: "INSTRUCTION_ENTRY_CHANGED", entryFile: state.entryFile });
|
|
state.entryFile = input.entryFile;
|
|
}
|
|
if (state.entryFile !== input.entryFile)
|
|
throw conflict(
|
|
"Configured instruction entry changed; read the current entry and retry",
|
|
{ code: "INSTRUCTION_ENTRY_CHANGED", entryFile: state.entryFile },
|
|
);
|
|
await assertInstructionPathSafe(state.root, state.entryFile);
|
|
const current = await currentFile(tx, input, state, bound);
|
|
const restored =
|
|
"restoreRevisionId" in input
|
|
? await getRevision(
|
|
tx,
|
|
input,
|
|
input.entryFile,
|
|
input.restoreRevisionId,
|
|
)
|
|
: null;
|
|
const candidate = bytes ?? Buffer.from(restored!.contentBase64, "base64");
|
|
if (current?.contentBase64 !== candidate.toString("base64")) {
|
|
await assertAgentInteraction(tx, { companyId: input.companyId, actorAgentId: bound.type === "agent" ? bound.agentId : null,
|
|
operation: "mention", texts: [submittedContent] });
|
|
}
|
|
const origin = currentPluginInteractionOrigin();
|
|
const recordSave = (row: Revision) => tx.insert(activityLog).values({ companyId: input.companyId,
|
|
actorType: origin ? "agent" : bound.type === "plugin" ? "plugin" : bound.type === "board" ? "user" : "agent",
|
|
actorId: origin?.agentId ?? (bound.type === "plugin" ? bound.pluginId : bound.type === "board" ? bound.userId : bound.agentId)!,
|
|
agentId: origin?.agentId ?? (bound.type === "agent" ? bound.agentId : null), runId: row.sourceRunId,
|
|
responsibleUserId: row.responsibleUserId, action: "agent.files_updated", entityType: "agent", entityId: input.agentId,
|
|
details: { path: input.entryFile, contentHash: row.contentHash, created: current === null, source: restored ? "legacy_restore" : (input as InstructionCommitInput).source } });
|
|
const bindEntry = async () => {
|
|
if (
|
|
!state.agent.adapterConfig.instructionsRootPath ||
|
|
!state.agent.adapterConfig.instructionsBundleMode ||
|
|
(bound.type === "plugin" && configuredEntryFile !== input.entryFile)
|
|
) {
|
|
await updateAgentConfigurationInTransaction(tx as unknown as Db, state.agent.id, {
|
|
adapterConfig: {
|
|
...state.agent.adapterConfig,
|
|
instructionsBundleMode: "managed",
|
|
instructionsRootPath: state.root,
|
|
instructionsEntryFile: state.entryFile,
|
|
instructionsFilePath: `${state.root}/${state.entryFile}`,
|
|
},
|
|
}, { allowPendingApprovalConfigUpdate: true });
|
|
}
|
|
};
|
|
// An exact replay can safely return the durable receipt even after its base
|
|
// advanced. Restore also deduplicates identical content, preserving history.
|
|
if (current && current.contentBase64 === candidate.toString("base64")) {
|
|
if (!await isAgentFileSaveRecorded(tx, state.agent, input.entryFile, current.contentHash)) await recordSave(current);
|
|
await bindEntry();
|
|
return { row: current, changed: false };
|
|
}
|
|
// A pre-upgrade run can still pin a historical UUID. Compare its bytes,
|
|
// never let the old head project over a newer directory.
|
|
const legacyBase = input.baseRevisionId && current?.id !== input.baseRevisionId
|
|
? await tx.select().from(revisions).where(and(owner(input, input.entryFile), eq(revisions.id, input.baseRevisionId))).then(rows => rows[0])
|
|
: null;
|
|
if ((current?.id ?? null) !== input.baseRevisionId && !(legacyBase && legacyBase.contentHash === current?.contentHash)) {
|
|
throw conflict(
|
|
"Instructions changed since the base revision. Read the current entry before saving.",
|
|
{
|
|
code: "INSTRUCTION_REVISION_CONFLICT",
|
|
baseRevisionId: input.baseRevisionId,
|
|
currentRevisionId: current?.id ?? null,
|
|
},
|
|
);
|
|
}
|
|
await invalidateAgentFileProjection(state.root);
|
|
await materializeInstructionBytes(state.root, state.entryFile, candidate);
|
|
await persistDurableAgentFiles(tx, state.agent, state.root);
|
|
const row = currentRow(input, input.entryFile, candidate, bound);
|
|
await recordSave(row);
|
|
await bindEntry();
|
|
return { row, changed: true };
|
|
});
|
|
return { ...snapshot(result.row), changed: result.changed, materialization: "current" };
|
|
}
|
|
|
|
async function history(
|
|
target: InstructionTarget & {
|
|
entryFile: string;
|
|
cursor?: string;
|
|
limit?: number;
|
|
},
|
|
actor: AuthorizationActor,
|
|
): Promise<AgentInstructionHistory> {
|
|
const limit = Math.max(1, Math.min(100, target.limit ?? 50));
|
|
return db.transaction(async (tx) => {
|
|
const state = await lockTarget(tx, target, actor);
|
|
const bound = await authorizeRead(tx, actor, target);
|
|
await currentFile(tx, target, state, bound);
|
|
instructionPath(target.entryFile);
|
|
const cursor = target.cursor
|
|
? await getRevision(tx, target, target.entryFile, target.cursor)
|
|
: null;
|
|
// Keep PostgreSQL timestamp precision; JS Date truncates microseconds and
|
|
// would skip revisions in the cursor's fractional millisecond.
|
|
const cursorTime = cursor
|
|
? sql`(select created_at from agent_instruction_revisions where id = ${cursor.id})`
|
|
: null;
|
|
const rows = await tx
|
|
.select(revisionMetadataColumns)
|
|
.from(revisions)
|
|
.where(
|
|
and(
|
|
owner(target, target.entryFile),
|
|
cursor && cursorTime
|
|
? or(
|
|
lt(revisions.createdAt, cursorTime),
|
|
and(
|
|
eq(revisions.createdAt, cursorTime),
|
|
lt(revisions.id, cursor.id),
|
|
),
|
|
)
|
|
: undefined,
|
|
),
|
|
)
|
|
.orderBy(desc(revisions.createdAt), desc(revisions.id))
|
|
.limit(limit + 1);
|
|
return {
|
|
revisions: rows.slice(0, limit).map(metadata),
|
|
nextCursor: rows.length > limit ? rows[limit - 1]!.id : null,
|
|
};
|
|
});
|
|
}
|
|
async function readRevision(
|
|
target: InstructionTarget & { entryFile: string; revisionId: string },
|
|
actor: AuthorizationActor,
|
|
) {
|
|
return db.transaction(async (tx) => {
|
|
await lockTarget(tx, target, actor);
|
|
await authorizeRead(tx, actor, target);
|
|
return snapshot(
|
|
await getRevision(
|
|
tx,
|
|
target,
|
|
instructionPath(target.entryFile),
|
|
target.revisionId,
|
|
),
|
|
);
|
|
});
|
|
}
|
|
async function diff(
|
|
target: InstructionTarget & {
|
|
entryFile: string;
|
|
fromRevisionId: string;
|
|
toRevisionId: string;
|
|
},
|
|
actor: AuthorizationActor,
|
|
): Promise<AgentInstructionDiff> {
|
|
const from = await readRevision(
|
|
{ ...target, revisionId: target.fromRevisionId },
|
|
actor,
|
|
);
|
|
const to = await readRevision(
|
|
{ ...target, revisionId: target.toRevisionId },
|
|
actor,
|
|
);
|
|
// Linear, bounded exact replacement diff. Code points keep surrogate pairs intact.
|
|
const a = Array.from(from.content),
|
|
b = Array.from(to.content);
|
|
let start = 0,
|
|
end = 0;
|
|
while (start < a.length && start < b.length && a[start] === b[start])
|
|
start++;
|
|
while (
|
|
end < a.length - start &&
|
|
end < b.length - start &&
|
|
a[a.length - end - 1] === b[b.length - end - 1]
|
|
)
|
|
end++;
|
|
return {
|
|
from,
|
|
to,
|
|
prefix: a.slice(0, start).join(""),
|
|
removed: a.slice(start, a.length - end).join(""),
|
|
added: b.slice(start, b.length - end).join(""),
|
|
suffix: end ? a.slice(-end).join("") : "",
|
|
};
|
|
}
|
|
return {
|
|
readCommittedForRuntime,
|
|
readCurrent,
|
|
readForPluginReset,
|
|
commitPluginReset: (input: Omit<InstructionCommitInput, "source"> & { configuredEntryFile: string }, actor: PluginResetActor) =>
|
|
commitInternal({ ...input, source: "api" }, actor, input.configuredEntryFile),
|
|
readRevision,
|
|
history,
|
|
diff,
|
|
materializeCurrent,
|
|
commit: (input: InstructionCommitInput, actor: AuthorizationActor) =>
|
|
commitInternal(input, actor),
|
|
restore: (
|
|
input: InstructionTarget & {
|
|
entryFile: string;
|
|
baseRevisionId: string;
|
|
revisionId: string;
|
|
},
|
|
actor: AuthorizationActor,
|
|
) =>
|
|
commitInternal({ ...input, restoreRevisionId: input.revisionId }, actor),
|
|
};
|
|
}
|