mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent turns run in a remote Runner sandbox. A server upgrade
detaches each running turn, and the new server must reconnect to its
Runner (restart recovery).
> - A reconnect runs the full turn preparation before it contacts the
Runner. On a new server, skill preparation downloads every saved skill
version again, under one lock for the whole company.
> - After an upgrade, many reconnects wait behind each other's
downloads. The Runner stops answering after about 2 minutes, so a late
reconnect loses the turn.
> - This pull request lets a reconnect to the same run's live remote
Runner use the exact saved skill versions, without downloading them and
without the lock.
> - The benefit is that skill preparation no longer adds to the
reconnect delay, and it does not grow with the number of reconnects.
Normal turn starts do not change.
## Linked Issues or Issue Description
**What happened?**
After an automatic staging upgrade, runs that the new server reached
late failed. The measured time from detach to reconnect was 114–152 s
for the failed runs. Turn preparation took 30–130 s, and skill
preparation alone took 46 s on one run.
**Expected behavior**
A reconnect to a live Runner reaches it quickly. Its speed must not
depend on how many other runs prepare skills at the same time.
**Steps to reproduce**
1. Run a remote Runner turn for each of many tasks in one company.
2. Upgrade the server while those turns run, so the new server starts
with an empty skill cache.
3. See that each reconnect waits in
`heartbeat.prepare.configuration_skills` for the company skill cache
lock and downloads the skills again.
**Paperclip version or commit**
master at 4228bcf89c
**Additional context**
Root cause: `withRuntimeSkillEntries` holds the company-wide skill cache
lock (a Postgres advisory lock) while it materializes each saved skill
version. A new server has an empty skill cache, so each reconnect
downloads its skills again, one run at a time. The Runner already has
these files, and the reconnect path does not read them.
## What Changed
- `company-skills.ts`: new `admittedVersionsOnly` option. It still
checks that each saved version exists and that the agent can read the
skill. It does not materialize the files or take the company skill cache
lock.
- `heartbeat/live-runner-adoption.ts`: `adoptsLiveRemoteRunner` is true
only for a `reattach_remote_runner` claim for this run, with the claim's
own lease owner, on a native run.
- `heartbeat/execution-configuration.ts`: uses the option only when all
of these are true: the reconnect gate is true, the run has its saved
native input with a runtime context, and the run has its saved skill
versions. In that case it times the phase as
`configuration_skills_adopted` and adds one lifecycle run event
(`skillPreparation: "reused_admitted"`).
- `heartbeat.ts`: passes the gate to execution configuration.
- `native-runtime/runtime-context.ts` and `native-session-executor.ts`:
on the same reconnect to a remote Runner filesystem, the Runner
controller describes the Runner's skills by their admitted digests. It
rehydrates the pinned skill files (which takes the same lock) only if it
must launch a Runner process and stage them. All other starts rehydrate
as before.
- `doc/execution-semantics.md`: describes the new behavior.
Not in this PR (by design): a separate "dispatch-only" reconnect path,
and a new startup scheduling lane. The native executor needs about 40
values from preparation (runner environment, MCP token, managed AI
credentials, the reattached execution target, run output). Connector and
instruction preparation also feed the session fingerprint. That cut is
not mechanical, so this PR removes the largest measured single cost
only.
Other `heartbeat.prepare.*` costs that stay on the reconnect path (use
post-upgrade timings to choose the next cut):
- `configuration_secrets`, `configuration_connector_assignments`,
`configuration_connection_instructions`,
`configuration_connector_skills`/`_delivery`,
`configuration_agent_identity`, `configuration_ai_runtime`
- `environment_selection`, `workspace` (retained lease resume and
realization), `session`, `task_context`, `run_identity`
- `github_environment`, `github_launchers`, `run_output`,
`runtime_services`, `instructions`, `runtime_selection` (including
`runtime_selection.skill_assets` and `runtime_selection.workspace_sync`)
- The wait from detach to "run started" (queue and controller-preparing
waits) is outside `heartbeat.prepare.*`.
## Verification
- New test `reconnects to a live remote Runner with its admitted skills
without re-downloading them or waiting on the cache`
(`server/src/__tests__/heartbeat-execution-configuration.test.ts`):
- It admits a run, deletes its skill cache (like a new server), and
holds the company cache lock.
- The reconnect preparation finishes while the lock is held. It returns
the same key, runtime name and version. The session fingerprint is
identical. The cache is not created again.
- Normal preparation of the same saved selection still waits for the
lock and materializes the files ("normal start unchanged").
- Red on master source: `A live Runner reattach must not queue behind
skill downloads: expected null not to be null`. Green with this change.
- New test in `managed-skill-content.test.ts`: with the cache lock held
and an empty cache, `prepareRuntimeContextSource` for a reconnect
returns at once with the admitted context. Its staging step and a normal
start still wait for the lock and then rehydrate the same digests.
- New `server/src/services/heartbeat/live-runner-adoption.test.ts`: the
gate is false for a normal start, a scheduled resume, a dead-Runner
resume, an incomplete bootstrap, another run's claim, a different lease
owner, and a legacy run.
- `npx vitest run
src/__tests__/heartbeat-execution-configuration.test.ts
src/__tests__/skill-version-cache.test.ts
src/services/native-runtime/native-runner-restart-recovery.integration.test.ts
src/services/heartbeat/live-runner-adoption.test.ts`: 289 passed, 14
skipped. After the controller change: restart-recovery, diskless
restart, runtime skill preservation, managed skill content, session
executor and execution configuration suites: 1686 passed, 14 skipped.
- `tsc --noEmit -p server/tsconfig.json`: pass.
- `pnpm verify` asks for broader coverage (exit 2). Required CI supplies
it.
After deploy, a reconnect run shows
`heartbeat.prepare.configuration_skills_adopted` and the
`reused_admitted` event, and no `skills.cache.acquire` or
`skills.version.materialize` phases.
## Risks
- Low. The option applies only to a same-run reconnect of a retained
remote Runner that has a saved runtime context and saved skill versions.
Every other start keeps the current path.
- Access revocation and deleted versions still fail the reconnect, as
before. A failure to download the files on this server no longer fails a
live reconnect, because the Runner already holds them.
- Nothing new is saved, so rows from older releases, two live servers,
and a deploy during a reconnect behave as before.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (code search, editing, shell, tests).
## 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>
706 lines
50 KiB
TypeScript
706 lines
50 KiB
TypeScript
import { createServer } from "node:http";
|
|
import { createS3StorageProvider } from "../storage/s3-provider.js";
|
|
import { skillInstallationMaintenance } from "../services/skill-installation-maintenance.js";
|
|
import { withSkillVersionCacheLock } from "../services/skill-version-cache.js";
|
|
import { skillPackageStore } from "../services/skill-package-store.js";
|
|
import { removeRuntimeAssetTree } from "../services/native-runtime/runtime-asset-retention.js";
|
|
import { eq } from "drizzle-orm";
|
|
import { writePaperclipSkillSyncPreference } from "@paperclipai/adapter-utils/server-utils";
|
|
import { materializeSelectedSkills, prepareRuntimeContextSource, rehydratePinnedSkillAssets } from "../services/native-runtime/runtime-context.js";
|
|
import { nativeRuntimeContextFixture } from "../services/native-runtime/runtime-context.test-fixture.js";
|
|
import { randomUUID } from "node:crypto";
|
|
import { execFile } from "node:child_process";
|
|
import { promisify } from "node:util";
|
|
import { fileURLToPath } from "node:url";
|
|
import { promises as fs } from "node:fs";
|
|
import os from "node:os";
|
|
import path from "node:path";
|
|
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
|
|
import { applyPendingMigrations, agents, heartbeatRuns, companySkills, companySkillVersions, companies, createDb, instanceSettings } from "@paperclipai/db";
|
|
import { companySkillService } from "../services/company-skills.js";
|
|
import * as storageModule from "../storage/index.js";
|
|
import { createStorageService } from "../storage/service.js";
|
|
import { createLocalDiskStorageProvider } from "../storage/local-disk-provider.js";
|
|
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
|
|
|
|
const externalDatabase = process.env.PAPERCLIP_SKILL_TEST_DATABASE_URL;
|
|
const support = externalDatabase ? { supported: true } : await getEmbeddedPostgresTestSupport();
|
|
if (!support.supported) console.warn("Managed skill integration database unavailable:", support);
|
|
describe.skipIf(!support.supported)("managed skills use committed versions", () => {
|
|
let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
|
let db: ReturnType<typeof createDb>;
|
|
let root: string;
|
|
let home: string;
|
|
const previousHome = process.env.PAPERCLIP_HOME;
|
|
const previousInstance = process.env.PAPERCLIP_INSTANCE_ID;
|
|
const previousStorage = process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED;
|
|
beforeAll(async () => {
|
|
if (externalDatabase) {
|
|
await applyPendingMigrations(externalDatabase);
|
|
database = { connectionString: externalDatabase, cleanup: async () => {} };
|
|
} else database = await startEmbeddedPostgresTestDatabase("managed-skill-content-");
|
|
db = createDb(database.connectionString);
|
|
root = await fs.mkdtemp(path.join(os.tmpdir(), "managed-skill-content-"));
|
|
home = path.join(root, "server-a");
|
|
process.env.PAPERCLIP_HOME = home;
|
|
process.env.PAPERCLIP_INSTANCE_ID = "default";
|
|
process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED = "true";
|
|
vi.spyOn(storageModule, "getStorageService").mockReturnValue(
|
|
createStorageService(createLocalDiskStorageProvider(path.join(root, "objects"))),
|
|
);
|
|
}, 30_000);
|
|
afterAll(async () => {
|
|
vi.restoreAllMocks();
|
|
if (previousHome === undefined) delete process.env.PAPERCLIP_HOME;
|
|
else process.env.PAPERCLIP_HOME = previousHome;
|
|
if (previousStorage === undefined) delete process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED;
|
|
else process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED = previousStorage;
|
|
await db?.$client.end({ timeout: 1 });
|
|
await database?.cleanup();
|
|
if (root) await removeRuntimeAssetTree(root);
|
|
if (previousInstance === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;
|
|
else process.env.PAPERCLIP_INSTANCE_ID = previousInstance;
|
|
});
|
|
async function company() {
|
|
const id = randomUUID();
|
|
await db.insert(companies).values({ id, name: "Managed content", issuePrefix: `M${id.slice(0, 6)}` });
|
|
return id;
|
|
}
|
|
|
|
it("imports supporting files from a root-level package without truncating their paths", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const [imported] = await service.importPackageFiles(companyId, {
|
|
"SKILL.md": "---\nname: Root package\n---\n# Root\n",
|
|
"references/guide.md": "complete root guide",
|
|
});
|
|
expect(imported).toBeTruthy();
|
|
const skills = await service.list(companyId);
|
|
const skill = skills.find(entry => entry.name === "Root package")!;
|
|
expect(await service.readFile(companyId, skill.id, "references/guide.md"))
|
|
.toMatchObject({ content: "complete root guide" });
|
|
});
|
|
|
|
it("loads persisted Cloud configuration for read-only maintenance without seeding it", async () => {
|
|
const companyId = await company();
|
|
const objects = new Map<string, Buffer>();
|
|
const server = createServer((request, response) => {
|
|
void (async () => {
|
|
const key = new URL(request.url!, "http://fixture").pathname;
|
|
if (request.method === "PUT") {
|
|
const chunks: Buffer[] = [];
|
|
for await (const chunk of request) chunks.push(Buffer.from(chunk));
|
|
let body = Buffer.concat(chunks);
|
|
if (request.headers["content-encoding"]?.includes("aws-chunked")) {
|
|
const decoded: Buffer[] = [];
|
|
let offset = 0;
|
|
while (offset < body.length) {
|
|
const end = body.indexOf("\r\n", offset);
|
|
const size = Number.parseInt(body.subarray(offset, end).toString().split(";")[0]!, 16);
|
|
if (size === 0) break;
|
|
decoded.push(body.subarray(end + 2, end + 2 + size)); offset = end + 2 + size + 2;
|
|
}
|
|
body = Buffer.concat(decoded);
|
|
}
|
|
objects.set(key, body); response.writeHead(200, { etag: '"fixture"' }).end(); return;
|
|
}
|
|
const body = objects.get(key);
|
|
if (!body) { response.writeHead(404).end(); return; }
|
|
response.writeHead(200, { "content-length": body.length, "content-type": "application/octet-stream", etag: '"fixture"' });
|
|
response.end(request.method === "HEAD" ? undefined : body);
|
|
})().catch(() => { response.writeHead(500).end(); });
|
|
});
|
|
await new Promise<void>(resolve => { server.listen(0, "127.0.0.1", resolve); });
|
|
const address = server.address(); if (!address || typeof address === "string") throw new Error("Expected fixture address");
|
|
const endpoint = `http://127.0.0.1:${address.port}`;
|
|
const credentials = { AWS_ACCESS_KEY_ID: "fixture-access-key", AWS_SECRET_ACCESS_KEY: "fixture-secret-key", AWS_SESSION_TOKEN: "" };
|
|
const previousCredentials = Object.fromEntries(Object.keys(credentials).map(key => [key, process.env[key]]));
|
|
Object.assign(process.env, credentials);
|
|
vi.mocked(storageModule.getStorageService).mockReturnValue(createStorageService(createS3StorageProvider({
|
|
bucket: "managed-skill-fixture", region: "us-east-1", endpoint, forcePathStyle: true,
|
|
})));
|
|
const key = "cloud-runtime-config:v1";
|
|
try {
|
|
await companySkillService(db).createLocalSkill(companyId, { name: "Cloud CLI", markdown: "# Cloud CLI" });
|
|
const run = (phase: string) => promisify(execFile)(process.execPath, [
|
|
"--import", fileURLToPath(import.meta.resolve("tsx")),
|
|
fileURLToPath(new URL("../../scripts/migrate-skill-packages.ts", import.meta.url)),
|
|
`--phase=${phase}`, `--company=${companyId}`, "--limit=50",
|
|
], { env: { ...process.env, ...credentials, DATABASE_URL: database.connectionString,
|
|
PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "disposable-cloud-cli-fixture",
|
|
PAPERCLIP_SECRETS_MASTER_KEY: "a".repeat(64), PAPERCLIP_STORAGE_PROVIDER: "s3",
|
|
PAPERCLIP_STORAGE_S3_BUCKET: "managed-skill-fixture", PAPERCLIP_STORAGE_S3_REGION: "us-east-1",
|
|
PAPERCLIP_STORAGE_S3_ENDPOINT: endpoint, PAPERCLIP_STORAGE_S3_FORCE_PATH_STYLE: "true", PAPERCLIP_STORAGE_S3_PREFIX: "" },
|
|
timeout: 60_000, maxBuffer: 1024 * 1024 });
|
|
await expect(run("eligibility")).rejects.toThrow("Initialize Cloud runtime configuration");
|
|
expect(await db.select().from(instanceSettings).where(eq(instanceSettings.singletonKey, key))).toHaveLength(0);
|
|
await db.insert(instanceSettings).values({ singletonKey: key, general: { version: 1, revision: 0, config: null } });
|
|
const eligibility = JSON.parse((await run("eligibility")).stdout.trim().split("\n").at(-1)!);
|
|
expect(eligibility.results).toEqual([expect.objectContaining({ status: "version_backed" })]);
|
|
const before = [...objects.entries()].map(([key, body]) => [key, Buffer.from(body)] as const);
|
|
const verification = JSON.parse((await run("verification")).stdout.trim().split("\n").at(-1)!);
|
|
expect(verification.results).toEqual([expect.objectContaining({ status: "remote_storage" })]);
|
|
expect([...objects.entries()]).toEqual(before);
|
|
const archiveKey = [...objects.keys()].find(key => key.endsWith("/files.tar.gz"))!;
|
|
const archive = objects.get(archiveKey)!;
|
|
const corrupted = Buffer.from(archive); corrupted[0] = corrupted[0]! ^ 1;
|
|
objects.set(archiveKey, corrupted);
|
|
const corrupt = JSON.parse((await run("verification")).stdout.trim().split("\n").at(-1)!);
|
|
expect(corrupt.results).toEqual([expect.objectContaining({ status: "corrupt_package" })]);
|
|
objects.set(archiveKey, archive);
|
|
const manifestKey = [...objects.keys()].find(key => key.endsWith("/manifest.json"))!;
|
|
const manifest = objects.get(manifestKey)!; objects.delete(manifestKey);
|
|
const unavailable = JSON.parse((await run("verification")).stdout.trim().split("\n").at(-1)!);
|
|
expect(unavailable.results).toEqual([expect.objectContaining({ status: "unavailable_or_corrupt_package" })]);
|
|
objects.set(manifestKey, manifest);
|
|
const recovered = JSON.parse((await run("verification")).stdout.trim().split("\n").at(-1)!);
|
|
expect(recovered.results).toEqual([expect.objectContaining({ status: "remote_storage" })]);
|
|
expect([...objects.entries()].sort()).toEqual([...before].sort());
|
|
expect(await db.select().from(instanceSettings).where(eq(instanceSettings.singletonKey, key)))
|
|
.toEqual([expect.objectContaining({ general: { version: 1, revision: 0, config: null } })]);
|
|
} finally {
|
|
await db.delete(instanceSettings).where(eq(instanceSettings.singletonKey, key));
|
|
vi.mocked(storageModule.getStorageService).mockReturnValue(createStorageService(createLocalDiskStorageProvider(path.join(root, "objects"))));
|
|
for (const [key, value] of Object.entries(previousCredentials)) {
|
|
if (value === undefined) delete process.env[key]; else process.env[key] = value;
|
|
}
|
|
server.closeAllConnections(); await new Promise<void>(resolve => { server.close(() => resolve()); });
|
|
}
|
|
}, 180_000);
|
|
|
|
it.each([
|
|
{ storage: "legacy local", env: { PAPERCLIP_STORAGE_PROVIDER: "local_disk" }, expectedStatus: "local_storage" },
|
|
{ storage: "shared S3", env: { PAPERCLIP_STORAGE_PROVIDER: "s3",
|
|
PAPERCLIP_STORAGE_S3_BUCKET: "managed-skill-cli-fixture", PAPERCLIP_STORAGE_S3_REGION: "us-east-1",
|
|
PAPERCLIP_SECRETS_MASTER_KEY: "12345678901234567890123456789012" }, expectedStatus: "provider_mismatch" },
|
|
])("loads persisted Cloud configuration for read-only $storage maintenance without seeding it", async ({ env, expectedStatus }) => {
|
|
const companyId = await company();
|
|
const skill = await companySkillService(db).createLocalSkill(companyId, { name: "Cloud CLI", markdown: "# Cloud CLI" });
|
|
const local = await skillInstallationMaintenance(db).verifyVersions({ companyId, limit: 50 });
|
|
expect(local.results).toEqual([expect.objectContaining({ versionId: skill.currentVersionId, status: "local_storage" })]);
|
|
const key = "cloud-runtime-config:v1";
|
|
const run = (phase: string, storageProvider?: "s3" | "local_disk") => promisify(execFile)(process.execPath, [
|
|
"--import", fileURLToPath(import.meta.resolve("tsx")),
|
|
fileURLToPath(new URL("../../scripts/migrate-skill-packages.ts", import.meta.url)),
|
|
`--phase=${phase}`, `--company=${companyId}`, "--limit=50",
|
|
], { env: { ...process.env, DATABASE_URL: database.connectionString,
|
|
PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "disposable-cloud-cli-fixture",
|
|
PAPERCLIP_STORAGE_LOCAL_DIR: path.join(root, "objects"), ...env,
|
|
...(storageProvider === undefined ? {} : { PAPERCLIP_STORAGE_PROVIDER: storageProvider }) },
|
|
timeout: 60_000, maxBuffer: 1024 * 1024 });
|
|
await expect(run("eligibility")).rejects.toThrow("Initialize Cloud runtime configuration");
|
|
expect(await db.select().from(instanceSettings).where(eq(instanceSettings.singletonKey, key))).toHaveLength(0);
|
|
const [persisted] = await db.insert(instanceSettings).values({ singletonKey: key, general: { version: 1, revision: 0, config: null } }).returning();
|
|
try {
|
|
const eligibility = JSON.parse((await run("eligibility")).stdout.trim().split("\n").at(-1)!);
|
|
expect(eligibility.results).toEqual([expect.objectContaining({ versionId: skill.currentVersionId, status: "version_backed" })]);
|
|
const verification = JSON.parse((await run("verification")).stdout.trim().split("\n").at(-1)!);
|
|
expect(verification.results).toEqual([expect.objectContaining({ versionId: skill.currentVersionId, status: expectedStatus })]);
|
|
if (env.PAPERCLIP_STORAGE_PROVIDER === "s3") {
|
|
const legacyVerification = JSON.parse((await run("verification", "local_disk")).stdout.trim().split("\n").at(-1)!);
|
|
expect(legacyVerification.results).toEqual([expect.objectContaining({ versionId: skill.currentVersionId, status: "local_storage" })]);
|
|
}
|
|
expect(await db.select().from(instanceSettings).where(eq(instanceSettings.singletonKey, key))).toEqual([persisted]);
|
|
} finally {
|
|
await db.delete(instanceSettings).where(eq(instanceSettings.singletonKey, key));
|
|
}
|
|
}, 180_000);
|
|
|
|
it("forks live linked-local content even when an older saved version exists", async () => {
|
|
const companyId = await company();
|
|
const directory = path.join(root, `linked-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# Linked\n");
|
|
await fs.writeFile(path.join(directory, "support.txt"), "old saved content");
|
|
const [linked] = await db.insert(companySkills).values({ companyId, key: "linked", slug: "linked", name: "Linked",
|
|
markdown: "# Linked\n", sourceType: "local_path", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }, { path: "support.txt", kind: "other" }] }).returning();
|
|
const service = companySkillService(db);
|
|
const saved = await service.createVersion(companyId, linked!.id);
|
|
await fs.writeFile(path.join(directory, "support.txt"), "current local content");
|
|
await fs.writeFile(path.join(directory, "added.txt"), "new local file");
|
|
const forked = await service.createLocalSkill(companyId, { name: "Live fork", forkedFromSkillId: linked!.id });
|
|
expect(await service.readFile(companyId, forked.id, "support.txt")).toMatchObject({ content: "current local content" });
|
|
expect(await service.readFile(companyId, forked.id, "added.txt")).toMatchObject({ content: "new local file" });
|
|
expect((await service.getVersion(companyId, linked!.id, saved.id))?.fileInventory)
|
|
.toContainEqual(expect.objectContaining({ path: "support.txt", content: "old saved content" }));
|
|
});
|
|
|
|
it("carries committed version preconditions through a multi-file linked-local restore", async () => {
|
|
const companyId = await company();
|
|
const directory = path.join(root, `restore-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# Original\n");
|
|
await fs.writeFile(path.join(directory, "support.txt"), "original support");
|
|
const [linked] = await db.insert(companySkills).values({ companyId, key: "linked", slug: "linked", name: "Linked",
|
|
markdown: "# Original\n", sourceType: "local_path", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }, { path: "support.txt", kind: "other" }] }).returning();
|
|
const service = companySkillService(db);
|
|
const saved = await service.createVersion(companyId, linked!.id);
|
|
const original = (await service.getVersion(companyId, linked!.id, saved.id))!;
|
|
await service.updateFile(companyId, linked!.id, "SKILL.md", "# Changed\n");
|
|
await service.updateFile(companyId, linked!.id, "support.txt", "changed support");
|
|
let versionId = (await service.readFile(companyId, linked!.id, "SKILL.md"))!.versionId;
|
|
expect(versionId).toBeTruthy();
|
|
for (const file of original.fileInventory) {
|
|
const result = await service.updateFile(companyId, linked!.id, file.path, file.content, null,
|
|
{ expectedVersionId: versionId });
|
|
expect(result.versionId).toBeTruthy();
|
|
expect(result.versionId).not.toBe(versionId);
|
|
versionId = result.versionId;
|
|
}
|
|
expect(await service.readFile(companyId, linked!.id, "SKILL.md")).toMatchObject({ content: "# Original\n", versionId });
|
|
expect(await service.readFile(companyId, linked!.id, "support.txt")).toMatchObject({ content: "original support", versionId });
|
|
});
|
|
|
|
it("keeps an unassigned skill, supporting bytes and executable mode across fresh homes", async () => {
|
|
const companyId = await company();
|
|
const a = companySkillService(db);
|
|
const skill = await a.createLocalSkill(companyId, { name: "Cold", slug: "cold", markdown: "# First\n" });
|
|
expect(skill.sourceType).toBe("managed");
|
|
expect(skill.sourceLocator).toBeNull();
|
|
expect(skill.currentVersionId).toBeTruthy();
|
|
await expect(fs.stat(path.join(home, "instances/default/skills", companyId, "cold"))).rejects.toMatchObject({ code: "ENOENT" });
|
|
const saved = await a.updateFile(companyId, skill.id, "scripts/run.sh", "#!/bin/sh\necho cold\n", null,
|
|
{ executable: true, expectedVersionId: skill.currentVersionId });
|
|
const binary = await a.updateFile(companyId, skill.id, "data.bin", "AP8H", null,
|
|
{ encoding: "base64", expectedVersionId: saved.versionId });
|
|
await fs.rm(home, { recursive: true, force: true });
|
|
process.env.PAPERCLIP_HOME = path.join(root, "server-b");
|
|
const b = companySkillService(db);
|
|
expect((await b.list(companyId)).some(item => item.id === skill.id)).toBe(true);
|
|
expect(await b.readFile(companyId, skill.id, "data.bin")).toMatchObject({ content: "AP8H", encoding: "base64", versionId: binary.versionId });
|
|
const updated = await b.updateFile(companyId, skill.id, "SKILL.md", "# Saved on B\n", null, { expectedVersionId: binary.versionId });
|
|
const [runtime] = await b.listRuntimeSkillEntries(companyId, { onlyKeys: new Set([skill.key]), snapshotLatest: true });
|
|
expect(runtime).toMatchObject({ versionId: updated.versionId, sourceStatus: "available" });
|
|
expect((await fs.stat(path.join(runtime!.source, "scripts/run.sh"))).mode & 0o111).not.toBe(0);
|
|
expect(await fs.readFile(path.join(runtime!.source, "data.bin"))).toEqual(Buffer.from([0, 255, 7]));
|
|
await fs.rm(process.env.PAPERCLIP_HOME, { recursive: true, force: true });
|
|
process.env.PAPERCLIP_HOME = path.join(root, "server-c");
|
|
expect(await companySkillService(db).readFile(companyId, skill.id, "SKILL.md"))
|
|
.toMatchObject({ content: "# Saved on B\n", versionId: updated.versionId });
|
|
expect(await a.readFile(companyId, skill.id, "SKILL.md")).toMatchObject({ versionId: updated.versionId });
|
|
});
|
|
|
|
it("rejects a save whose base changed while its package was being prepared", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Race" });
|
|
await expect(service.updateFile(companyId, skill.id, "first.md", "first", null, { publication: {
|
|
beforeLock: async () => { await service.updateFile(companyId, skill.id, "second.md", "second"); },
|
|
} })).rejects.toMatchObject({ status: 409 });
|
|
expect(await service.readFile(companyId, skill.id, "second.md")).toMatchObject({ content: "second" });
|
|
await expect(service.readFile(companyId, skill.id, "first.md")).rejects.toMatchObject({ status: 404 });
|
|
await expect(service.updateFile(companyId, skill.id, "first.md", "stale", null,
|
|
{ expectedVersionId: skill.currentVersionId })).rejects.toMatchObject({ status: 409 });
|
|
});
|
|
|
|
it("rolls back publication without changing the head or an existing version", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Rollback", markdown: "# Original" });
|
|
await expect(service.updateFile(companyId, skill.id, "SKILL.md", "# Rejected", null,
|
|
{ publication: { afterPublish: async () => { throw new Error("failed audit"); } } })).rejects.toThrow("failed audit");
|
|
expect(await service.readFile(companyId, skill.id, "SKILL.md")).toMatchObject({ content: "# Original", versionId: skill.currentVersionId });
|
|
expect(await service.listVersions(companyId, skill.id)).toHaveLength(1);
|
|
});
|
|
|
|
it("does not overwrite a metadata edit committed while content was being prepared", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Metadata race", markdown: "# Original" });
|
|
await expect(service.updateFile(companyId, skill.id, "SKILL.md", "# Candidate", null, { publication: {
|
|
beforeLock: async () => { await service.updateSkill(companyId, skill.id, { description: "Acknowledged metadata" }); },
|
|
} })).rejects.toMatchObject({ status: 409 });
|
|
expect(await service.getById(companyId, skill.id)).toMatchObject({ description: "Acknowledged metadata", currentVersionId: skill.currentVersionId });
|
|
expect(await service.readFile(companyId, skill.id, "SKILL.md")).toMatchObject({ content: "# Original" });
|
|
});
|
|
|
|
it("restores the exact historical inventory and preserves history through rename and fork", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "History", markdown: "# Original" });
|
|
const extra = await service.updateFile(companyId, skill.id, "new.md", "not in first version");
|
|
const restored = await service.createVersion(companyId, skill.id,
|
|
{ sourceVersionId: skill.currentVersionId!, expectedVersionId: extra.versionId });
|
|
await expect(service.readFile(companyId, skill.id, "new.md")).rejects.toMatchObject({ status: 404 });
|
|
const renamed = await service.renameSkill(companyId, skill.id, { name: "Renamed", expectedVersionId: restored.id });
|
|
expect(renamed.skill).toMatchObject({ id: skill.id, sourceType: "managed", sourceLocator: null });
|
|
expect((await service.getVersion(companyId, skill.id, skill.currentVersionId!))!.fileInventory)
|
|
.toContainEqual({ path: "SKILL.md", kind: "skill", content: "# Original" });
|
|
const fork = await service.forkSkill(companyId, skill.id);
|
|
expect(fork.skill).toMatchObject({ sourceType: "managed", sourceLocator: null, forkedFromSkillId: skill.id });
|
|
expect((await service.readFile(companyId, fork.skill.id, "SKILL.md"))!.content)
|
|
.toBe((await service.readFile(companyId, skill.id, "SKILL.md"))!.content);
|
|
});
|
|
it("persists selection before delivery and rejects deleting a detached active run's pin", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Pinned", markdown: "# pinned bytes" });
|
|
const [agent] = await db.insert(agents).values({ companyId, name: "Runner" }).returning();
|
|
const [run] = await db.insert(heartbeatRuns).values({ companyId, agentId: agent!.id, status: "running" }).returning();
|
|
let persisted = false;
|
|
const entries = await service.withRuntimeSkillEntries(companyId, {
|
|
onlyKeys: new Set([skill.key]), snapshotLatest: true,
|
|
selectVersions: async selected => {
|
|
expect(selected).toEqual([expect.objectContaining({ skillId: skill.id, versionId: skill.currentVersionId })]);
|
|
expect(selected[0]).not.toHaveProperty("source");
|
|
await expect(fs.stat(path.join(process.env.PAPERCLIP_HOME!, "instances/default/skills", companyId,
|
|
"__versions__", skill.id, skill.currentVersionId!))).rejects.toMatchObject({ code: "ENOENT" });
|
|
await db.update(heartbeatRuns).set({ contextSnapshot: { skillVersions: { [skill.key]: skill.currentVersionId }, skillSelectionSnapshot: true } })
|
|
.where(eq(heartbeatRuns.id, run!.id));
|
|
persisted = true;
|
|
return new Set([skill.key]);
|
|
},
|
|
}, async entries => { expect(persisted).toBe(true); return entries; });
|
|
const config = writePaperclipSkillSyncPreference({}, [{ key: skill.key, versionId: skill.currentVersionId }]);
|
|
const selected = await materializeSelectedSkills(config, entries, false);
|
|
const context = { ...nativeRuntimeContextFixture(), skills: selected };
|
|
const originalHome = process.env.PAPERCLIP_HOME!;
|
|
process.env.PAPERCLIP_HOME = path.join(root, `recovery-${randomUUID()}`);
|
|
const recovered = await rehydratePinnedSkillAssets(db, { companyId, agentId: agent!.id, runId: run!.id }, context);
|
|
expect(recovered.skills[0]!.bundle.digest).toBe(selected[0]!.bundle.digest);
|
|
expect(recovered.skills[0]!.bundle.rootPath).not.toBe(selected[0]!.bundle.rootPath);
|
|
expect(await fs.readFile(path.join(recovered.skills[0]!.bundle.rootPath, "SKILL.md"), "utf8")).toBe("# pinned bytes");
|
|
await expect(rehydratePinnedSkillAssets(db, { companyId, agentId: agent!.id, runId: run!.id }, {
|
|
...context, skills: [{ ...selected[0]!, bundle: { ...selected[0]!.bundle, digest: "0".repeat(64) } }],
|
|
})).rejects.toThrow("admitted digest");
|
|
await expect(service.deleteSkill(companyId, skill.id)).rejects.toMatchObject({ status: 422 });
|
|
await db.update(heartbeatRuns).set({ status: "succeeded", finishedAt: new Date() }).where(eq(heartbeatRuns.id, run!.id));
|
|
await expect(service.deleteSkill(companyId, skill.id)).resolves.toMatchObject({ id: skill.id });
|
|
process.env.PAPERCLIP_HOME = originalHome;
|
|
});
|
|
|
|
it("reconnects to a live remote Runner without rehydrating its pinned skills until a launch stages them", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Reconnect pinned", markdown: "# reconnect bytes" });
|
|
const [agent] = await db.insert(agents).values({ companyId, name: "Runner" }).returning();
|
|
const [run] = await db.insert(heartbeatRuns).values({ companyId, agentId: agent!.id, status: "running",
|
|
contextSnapshot: { skillVersions: { [skill.key]: skill.currentVersionId }, skillSelectionSnapshot: true } }).returning();
|
|
const entries = await service.withRuntimeSkillEntries(companyId, { onlyKeys: new Set([skill.key]), snapshotLatest: true,
|
|
versionSelections: new Map([[skill.key, skill.currentVersionId!]]) }, async entries => entries);
|
|
const selected = await materializeSelectedSkills(writePaperclipSkillSyncPreference({}, [{ key: skill.key, versionId: skill.currentVersionId }]), entries, false);
|
|
const context = { ...nativeRuntimeContextFixture(), skills: selected };
|
|
const binding = { companyId, agentId: agent!.id, runId: run!.id };
|
|
// A run saved before skill selections were recorded has no proof that preparation checked access.
|
|
const [older] = await db.insert(heartbeatRuns).values({ companyId, agentId: agent!.id, status: "running", contextSnapshot: {} }).returning();
|
|
const originalHome = process.env.PAPERCLIP_HOME!;
|
|
// A newly deployed server: its skill cache is empty.
|
|
process.env.PAPERCLIP_HOME = path.join(root, `reconnect-${randomUUID()}`);
|
|
let release!: () => void;
|
|
let acquired!: () => void;
|
|
const ready = new Promise<void>(resolve => { acquired = resolve; });
|
|
const barrier = new Promise<void>(resolve => { release = resolve; });
|
|
const holder = withSkillVersionCacheLock(db, companyId, async () => { acquired(); await barrier; });
|
|
await ready;
|
|
const settledWithin = async <T>(work: Promise<T>, ms: number) => {
|
|
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
try { return await Promise.race([work.then(value => ({ value })), new Promise<null>(resolve => { timer = setTimeout(() => resolve(null), ms); })]); }
|
|
finally { if (timer) clearTimeout(timer); }
|
|
};
|
|
let staging: Promise<unknown> | undefined;
|
|
let fresh: Promise<unknown> | undefined;
|
|
let unpinned: Promise<unknown> | undefined;
|
|
try {
|
|
const reconnect = await settledWithin(prepareRuntimeContextSource(db, binding, context, { deferUntilStaged: true }), 2_000);
|
|
expect(reconnect, "A live Runner reconnect must not wait on the skill cache").not.toBeNull();
|
|
expect(reconnect!.value.described).toBe(context);
|
|
staging = reconnect!.value.forStaging();
|
|
fresh = prepareRuntimeContextSource(db, binding, context, { deferUntilStaged: false });
|
|
// Staging a relaunch, and every other start, still rehydrate under the cache lock.
|
|
expect(await settledWithin(staging, 200)).toBeNull();
|
|
expect(await settledWithin(fresh, 200)).toBeNull();
|
|
unpinned = prepareRuntimeContextSource(db, { ...binding, runId: older!.id }, context, { deferUntilStaged: true });
|
|
expect(await settledWithin(unpinned, 200), "An older reconnect still rehydrates and checks access first").toBeNull();
|
|
} finally {
|
|
release();
|
|
await holder;
|
|
}
|
|
const restaged = await staging as Awaited<ReturnType<typeof rehydratePinnedSkillAssets>>;
|
|
expect(restaged.skills[0]!.bundle.digest).toBe(selected[0]!.bundle.digest);
|
|
expect(await fs.readFile(path.join(restaged.skills[0]!.bundle.rootPath, "SKILL.md"), "utf8")).toBe("# reconnect bytes");
|
|
const started = await fresh as Awaited<ReturnType<typeof prepareRuntimeContextSource>>;
|
|
expect(started.described.skills[0]!.bundle.digest).toBe(selected[0]!.bundle.digest);
|
|
expect((await unpinned as Awaited<ReturnType<typeof prepareRuntimeContextSource>>).described.skills[0]!.bundle.rootPath)
|
|
.not.toBe(selected[0]!.bundle.rootPath);
|
|
await db.update(heartbeatRuns).set({ status: "succeeded", finishedAt: new Date() }).where(eq(heartbeatRuns.id, run!.id));
|
|
await db.update(heartbeatRuns).set({ status: "succeeded", finishedAt: new Date() }).where(eq(heartbeatRuns.id, older!.id));
|
|
process.env.PAPERCLIP_HOME = originalHome;
|
|
});
|
|
|
|
it("converts a legacy managed installation without changing its identity or identical version", async () => {
|
|
const companyId = await company();
|
|
const directory = path.join(root, `legacy-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# legacy saved");
|
|
await fs.writeFile(path.join(directory, "support.txt"), "support");
|
|
const [legacy] = await db.insert(companySkills).values({ companyId, key: `company/${companyId}/legacy`, slug: "legacy",
|
|
name: "Legacy", markdown: "# legacy saved", sourceType: "local_path", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }, { path: "support.txt", kind: "other" }],
|
|
metadata: { sourceKind: "managed_local" } }).returning();
|
|
const service = companySkillService(db);
|
|
const version = await service.createVersion(companyId, legacy!.id);
|
|
await db.update(companySkillVersions).set({ packageFileMap: null }).where(eq(companySkillVersions.id, version.id));
|
|
const maintenance = skillInstallationMaintenance(db);
|
|
expect((await maintenance.installations({ id: legacy!.id })).results[0]!.status).toBe("conversion_required");
|
|
expect((await maintenance.installations({ id: legacy!.id, apply: true })).results)
|
|
.toEqual([expect.objectContaining({ skillId: legacy!.id, versionId: version.id, status: "converted" })]);
|
|
await fs.rm(directory, { recursive: true });
|
|
expect(await service.getById(companyId, legacy!.id)).toMatchObject({ sourceType: "managed", sourceLocator: null, currentVersionId: version.id });
|
|
expect(await service.readFile(companyId, legacy!.id, "support.txt")).toMatchObject({ content: "support" });
|
|
expect((await maintenance.eligibility({ id: legacy!.id })).results[0]!.status).toBe("version_backed");
|
|
});
|
|
|
|
it("copies an installation online while preserving unknown old pins, old inline bytes, files, and active work", async () => {
|
|
const companyId = await company(), directory = path.join(root, `copy-only-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# Preserved skill");
|
|
const [skill] = await db.insert(companySkills).values({ companyId, key: "copy-only", slug: "copy-only", name: "Copy only",
|
|
markdown: "# Preserved skill", sourceType: "local_path", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }], metadata: { sourceKind: "managed_local" } }).returning();
|
|
const files = [{ path: "SKILL.md", kind: "skill" as const, content: "# Preserved skill" }];
|
|
const [version] = await db.insert(companySkillVersions).values({ companyId, companySkillId: skill.id,
|
|
revisionNumber: 1, fileInventory: files }).returning();
|
|
await db.update(companySkills).set({ currentVersionId: version.id }).where(eq(companySkills.id, skill.id));
|
|
const [agent] = await db.insert(agents).values({ companyId, name: "Unrelated active worker" }).returning();
|
|
const [active] = await db.insert(heartbeatRuns).values({ companyId, agentId: agent.id, runtimeMode: "native",
|
|
status: "running", contextSnapshot: {} }).returning();
|
|
const maintenance = skillInstallationMaintenance(db);
|
|
expect((await maintenance.installations({ id: skill.id, apply: true })).results)
|
|
.toEqual([expect.objectContaining({ skillId: skill.id, status: "converted" })]);
|
|
expect((await db.select().from(companySkillVersions).where(eq(companySkillVersions.id, version.id)))[0].fileInventory).toEqual(files);
|
|
expect(await fs.readFile(path.join(directory, "SKILL.md"), "utf8")).toBe("# Preserved skill");
|
|
expect((await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, active.id)))[0]).toEqual(active);
|
|
// Copy-only publication does not release retention or volume-removal guards.
|
|
expect((await maintenance.eligibility({ id: skill.id })).results[0].status).toBe("unsupported_active_run");
|
|
});
|
|
|
|
it.each(["files", "source_locator"])("keeps a concurrent %s change instead of publishing the earlier conversion", async change => {
|
|
const companyId = await company(), directory = path.join(root, `conversion-race-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# Race");
|
|
await fs.writeFile(path.join(directory, "support.txt"), "old version");
|
|
const [skill] = await db.insert(companySkills).values({ companyId, key: "conversion-race", slug: "conversion-race", name: "Race",
|
|
markdown: "# Race", sourceType: "local_path", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }, { path: "support.txt", kind: "other" }],
|
|
metadata: { sourceKind: "managed_local" } }).returning();
|
|
const version = await companySkillService(db).createVersion(companyId, skill.id);
|
|
await fs.writeFile(path.join(directory, "support.txt"), "captured unsaved edit");
|
|
const storage = storageModule.getStorageService(), put = storage.putFile.bind(storage);
|
|
let changed = false;
|
|
const nextDirectory = path.join(root, `new-source-${randomUUID()}`);
|
|
const upload = vi.spyOn(storage, "putFile").mockImplementation(async input => {
|
|
const saved = await put(input);
|
|
if (!changed) {
|
|
changed = true;
|
|
if (change === "files") await fs.writeFile(path.join(directory, "support.txt"), "newer unsaved edit");
|
|
else {
|
|
await fs.mkdir(nextDirectory);
|
|
await fs.writeFile(path.join(nextDirectory, "SKILL.md"), "# New source");
|
|
await db.transaction(async tx => {
|
|
await tx.select().from(companySkills).where(eq(companySkills.id, skill.id)).for("update");
|
|
await tx.update(companySkills).set({ sourceLocator: nextDirectory }).where(eq(companySkills.id, skill.id));
|
|
});
|
|
}
|
|
}
|
|
return saved;
|
|
});
|
|
try {
|
|
const result = await skillInstallationMaintenance(db, storage).installations({ id: skill.id, apply: true });
|
|
expect(changed).toBe(true);
|
|
expect(result.results).toEqual([expect.objectContaining({ status: "blocked" })]);
|
|
const [current] = await db.select().from(companySkills).where(eq(companySkills.id, skill.id));
|
|
expect(current).toMatchObject({ sourceType: "local_path", currentVersionId: version.id,
|
|
sourceLocator: change === "files" ? directory : nextDirectory });
|
|
expect(await fs.readFile(path.join(directory, "support.txt"), "utf8"))
|
|
.toBe(change === "files" ? "newer unsaved edit" : "captured unsaved edit");
|
|
} finally { upload.mockRestore(); }
|
|
});
|
|
|
|
it("holds a hard-linked local skill instead of adopting another file owner's mutable bytes", async () => {
|
|
const companyId = await company(), directory = path.join(root, `linked-conversion-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
const original = path.join(root, `shared-content-${randomUUID()}.md`);
|
|
await fs.writeFile(original, "# Shared source");
|
|
await fs.link(original, path.join(directory, "SKILL.md"));
|
|
const [skill] = await db.insert(companySkills).values({ companyId, key: "linked-conversion", slug: "linked-conversion", name: "Linked",
|
|
markdown: "# Shared source", sourceType: "local_path", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }], metadata: { sourceKind: "managed_local" } }).returning();
|
|
expect((await skillInstallationMaintenance(db).installations({ id: skill.id, apply: true })).results)
|
|
.toEqual([expect.objectContaining({ status: "blocked" })]);
|
|
expect((await db.select().from(companySkills).where(eq(companySkills.id, skill.id)))[0]).toEqual(skill);
|
|
expect(await fs.readFile(original, "utf8")).toBe("# Shared source");
|
|
});
|
|
|
|
it("allows new durable skill pinning while an installation upload is blocked", async () => {
|
|
const companyId = await company(), directory = path.join(root, `pinning-during-copy-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# Old selection");
|
|
const [skill] = await db.insert(companySkills).values({ companyId, key: "online-pinning", slug: "online-pinning", name: "Pinning",
|
|
markdown: "# Old selection", sourceType: "local_path", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }], metadata: { sourceKind: "managed_local" } }).returning();
|
|
const version = await companySkillService(db).createVersion(companyId, skill.id);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), `# Current local files ${randomUUID()}`);
|
|
const [agent] = await db.insert(agents).values({ companyId, name: "New work" }).returning();
|
|
const [run] = await db.insert(heartbeatRuns).values({ companyId, agentId: agent.id, status: "queued" }).returning();
|
|
const storage = storageModule.getStorageService(), put = storage.putFile.bind(storage);
|
|
let release!: () => void, ready!: () => void, blocked = false;
|
|
const barrier = new Promise<void>(resolve => { release = resolve; }), uploading = new Promise<void>(resolve => { ready = resolve; });
|
|
const upload = vi.spyOn(storage, "putFile").mockImplementation(async input => {
|
|
if (!blocked) { blocked = true; ready(); await barrier; }
|
|
return put(input);
|
|
});
|
|
const conversion = skillInstallationMaintenance(db, storage).installations({ id: skill.id, apply: true });
|
|
try {
|
|
await uploading;
|
|
// This uses the real nonblocking PostgreSQL owner, not a timing assertion.
|
|
await withSkillVersionCacheLock(db, companyId, async () => {
|
|
await db.update(heartbeatRuns).set({ status: "running", contextSnapshot: { skillVersions: { [skill.key]: version.id } } })
|
|
.where(eq(heartbeatRuns.id, run.id));
|
|
}, true);
|
|
} finally { release(); await conversion; upload.mockRestore(); }
|
|
expect((await conversion).results).toEqual([expect.objectContaining({ status: "converted" })]);
|
|
expect((await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, run.id)))[0])
|
|
.toMatchObject({ status: "running", contextSnapshot: { skillVersions: { [skill.key]: version.id } } });
|
|
expect((await db.select().from(companySkillVersions).where(eq(companySkillVersions.id, version.id)))[0]).toBeDefined();
|
|
});
|
|
|
|
it.each([true, false])("keeps catalog history unchanged on rejection and preserves its reset version (concurrent edit: %s)", async concurrentEdit => {
|
|
const companyId = await company(), directory = path.join(root, `catalog-copy-${randomUUID()}`), origin = `${directory}-original`;
|
|
await fs.mkdir(directory); await fs.mkdir(origin);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# Installed edit");
|
|
await fs.writeFile(path.join(origin, "SKILL.md"), "# Original package");
|
|
const [skill] = await db.insert(companySkills).values({ companyId, key: "catalog-copy", slug: "catalog-copy", name: "Catalog",
|
|
markdown: "# Installed edit", sourceType: "catalog", sourceLocator: directory,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }], metadata: {
|
|
sourceKind: "catalog", originSnapshotLocator: origin, userModifiedAt: new Date().toISOString(),
|
|
} }).returning();
|
|
const [version] = await db.insert(companySkillVersions).values({ companyId, companySkillId: skill.id, revisionNumber: 1,
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill", content: "# Installed edit" }] }).returning();
|
|
await db.update(companySkills).set({ currentVersionId: version.id }).where(eq(companySkills.id, skill.id));
|
|
const storage = storageModule.getStorageService(), put = storage.putFile.bind(storage);
|
|
let changed = false;
|
|
const upload = vi.spyOn(storage, "putFile").mockImplementation(async input => {
|
|
const saved = await put(input);
|
|
if (!changed) {
|
|
changed = true;
|
|
if (concurrentEdit) await fs.writeFile(path.join(origin, "SKILL.md"), "# Concurrent original edit");
|
|
}
|
|
return saved;
|
|
});
|
|
try {
|
|
expect((await skillInstallationMaintenance(db, storage).installations({ id: skill.id, apply: true })).results)
|
|
.toEqual([expect.objectContaining({ status: concurrentEdit ? "blocked" : "converted" })]);
|
|
expect(changed).toBe(true);
|
|
const history = await db.select().from(companySkillVersions).where(eq(companySkillVersions.companySkillId, skill.id));
|
|
expect(history).toHaveLength(concurrentEdit ? 1 : 2);
|
|
expect(history.find(row => row.id === version.id)).toMatchObject({ fileInventory: version.fileInventory });
|
|
const [current] = await db.select().from(companySkills).where(eq(companySkills.id, skill.id));
|
|
if (concurrentEdit) expect(current.metadata?.originVersionId).toBeUndefined();
|
|
else {
|
|
const original = history.find(row => row.id !== version.id)!;
|
|
expect(current.metadata?.originVersionId).toBe(original.id);
|
|
const store = skillPackageStore(db, storage), saved = await store.version(companyId, skill.id, original.id);
|
|
expect((await store.versionFiles(saved!)).find(file => file.path === "SKILL.md")?.content).toBe("# Original package");
|
|
}
|
|
expect(await fs.readFile(path.join(origin, "SKILL.md"), "utf8"))
|
|
.toBe(concurrentEdit ? "# Concurrent original edit" : "# Original package");
|
|
} finally { upload.mockRestore(); }
|
|
});
|
|
|
|
it("reports an unrecoverable legacy installation and leaves linked sources alone", async () => {
|
|
const companyId = await company();
|
|
const [legacy] = await db.insert(companySkills).values({ companyId, key: "legacy-missing", slug: "legacy-missing", name: "Missing",
|
|
markdown: "partial metadata only", sourceType: "local_path", sourceLocator: path.join(root, "absent"),
|
|
metadata: { sourceKind: "managed_local" } }).returning();
|
|
const [linked] = await db.insert(companySkills).values({ companyId, key: "linked", slug: "linked", name: "Linked",
|
|
markdown: "# Linked", sourceType: "local_path", sourceLocator: path.join(root, "linked") }).returning();
|
|
const report = await skillInstallationMaintenance(db).installations({ companyId, apply: true, writersStopped: true });
|
|
expect(report.results).toEqual(expect.arrayContaining([
|
|
expect.objectContaining({ skillId: legacy!.id, status: "blocked" }),
|
|
expect.objectContaining({ skillId: linked!.id, status: "linked_local" }),
|
|
]));
|
|
expect(await companySkillService(db).getById(companyId, legacy!.id)).toMatchObject({ sourceType: "local_path", currentVersionId: null });
|
|
});
|
|
|
|
it("converts a missing legacy directory from its complete saved version", async () => {
|
|
const companyId = await company();
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Saved conversion", markdown: "# saved" });
|
|
const saved = await service.updateFile(companyId, skill.id, "support.txt", "complete supporting content");
|
|
await db.update(companySkills).set({ sourceType: "local_path", sourceLocator: path.join(root, "missing-legacy"),
|
|
metadata: { sourceKind: "managed_local" } }).where(eq(companySkills.id, skill.id));
|
|
const maintenance = skillInstallationMaintenance(db);
|
|
expect((await maintenance.installations({ id: skill.id, apply: true, writersStopped: true })).results)
|
|
.toEqual([expect.objectContaining({ skillId: skill.id, versionId: saved.versionId, status: "converted" })]);
|
|
expect((await maintenance.installations({ id: skill.id, apply: true, writersStopped: true })).results[0]!.status).toBe("unchanged");
|
|
expect(await service.readFile(companyId, skill.id, "support.txt")).toMatchObject({ content: "complete supporting content" });
|
|
});
|
|
|
|
it.each([false, true])("blocks an incomplete installed repository version and converts only its exact source (package: %s)", async packaged => {
|
|
const companyId = await company(), service = companySkillService(db);
|
|
process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED = String(packaged);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Partial legacy repository", markdown: "# Installed revision" });
|
|
process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED = "true";
|
|
const commit = "a".repeat(40);
|
|
await db.update(companySkills).set({ sourceType: "github", sourceLocator: `https://github.com/fixture/skills/tree/${commit}/fixture`,
|
|
sourceRef: commit, metadata: { owner: "fixture", repo: "skills", repoSkillDir: "fixture" },
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }, { path: "reference.md", kind: "reference" }],
|
|
}).where(eq(companySkills.id, skill.id));
|
|
const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("unavailable", { status: 404 }));
|
|
try {
|
|
const maintenance = skillInstallationMaintenance(db);
|
|
expect((await maintenance.eligibility({ id: skill.id })).results[0]).toMatchObject({ status: "incomplete_current_version" });
|
|
expect((await maintenance.verifyVersions({ id: skill.currentVersionId! })).results[0]).toMatchObject({ status: "incomplete_current_version" });
|
|
expect(fetchMock).not.toHaveBeenCalled();
|
|
expect((await maintenance.installations({ id: skill.id, apply: true, writersStopped: true })).results[0]).toMatchObject({ status: "blocked" });
|
|
expect((await db.select().from(companySkills).where(eq(companySkills.id, skill.id)))[0].currentVersionId).toBe(skill.currentVersionId);
|
|
fetchMock.mockImplementation(async url => {
|
|
expect(String(url)).toBe(`https://raw.githubusercontent.com/fixture/skills/${commit}/fixture/reference.md`);
|
|
return new Response("Exact installed supporting content");
|
|
});
|
|
expect((await maintenance.installations({ id: skill.id, apply: true, writersStopped: true })).results[0]).toMatchObject({ status: "converted" });
|
|
expect(await service.readFile(companyId, skill.id, "reference.md")).toMatchObject({ content: "Exact installed supporting content" });
|
|
expect((await maintenance.eligibility({ id: skill.id })).results[0]).toMatchObject({ status: "version_backed" });
|
|
expect((await maintenance.verifyVersions({ companyId })).results.every(row => row.status !== "incomplete_current_version")).toBe(true);
|
|
const calls = fetchMock.mock.calls.length;
|
|
expect((await maintenance.installations({ id: skill.id })).results[0]).toMatchObject({ status: "unchanged" });
|
|
expect(fetchMock).toHaveBeenCalledTimes(calls);
|
|
} finally { fetchMock.mockRestore(); }
|
|
});
|
|
|
|
it("rejects unsafe legacy sources without publishing a partial conversion", async () => {
|
|
const companyId = await company();
|
|
const directory = path.join(root, `unsafe-${randomUUID()}`);
|
|
await fs.mkdir(directory);
|
|
await fs.writeFile(path.join(directory, "SKILL.md"), "# legacy");
|
|
await fs.symlink(path.join(root, "unrelated"), path.join(directory, "support.txt"));
|
|
try {
|
|
const [legacy] = await db.insert(companySkills).values({ companyId, key: "unsafe", slug: "unsafe", name: "Unsafe", markdown: "# legacy",
|
|
sourceType: "local_path", sourceLocator: directory, metadata: { sourceKind: "managed_local" } }).returning();
|
|
expect((await skillInstallationMaintenance(db).installations({ id: legacy!.id, apply: true, writersStopped: true })).results)
|
|
.toEqual([expect.objectContaining({ status: "blocked", reason: "Legacy skill contains a symbolic link" })]);
|
|
expect(await companySkillService(db).getById(companyId, legacy!.id)).toMatchObject({ sourceType: "local_path", currentVersionId: null });
|
|
} finally { await fs.unlink(path.join(directory, "support.txt")); }
|
|
});
|
|
|
|
it("keeps the compatibility override durable in Postgres and reports that storage accurately", async () => {
|
|
const companyId = await company();
|
|
process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED = "false";
|
|
try {
|
|
const service = companySkillService(db);
|
|
const skill = await service.createLocalSkill(companyId, { name: "Inline durable", markdown: "# database bytes" });
|
|
const saved = await service.updateFile(companyId, skill.id, "support.txt", "also in Postgres");
|
|
expect((await skillInstallationMaintenance(db).verifyVersions({ id: saved.versionId! })).results)
|
|
.toEqual([expect.objectContaining({ status: "database_snapshot", packageId: null })]);
|
|
const priorHome = process.env.PAPERCLIP_HOME;
|
|
process.env.PAPERCLIP_HOME = path.join(root, `inline-cold-${randomUUID()}`);
|
|
try {
|
|
expect(await companySkillService(db).readFile(companyId, skill.id, "support.txt")).toMatchObject({ content: "also in Postgres" });
|
|
} finally { process.env.PAPERCLIP_HOME = priorHome; }
|
|
} finally { process.env.PAPERCLIP_SKILL_PACKAGE_STORAGE_ENABLED = "true"; }
|
|
});
|
|
|
|
});
|