mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A hosted server can move its durable data to shared storage while it serves work, and then run without a volume > - A bounded online pass moves the data, and a readiness check names what still blocks the move > - Some servers stay blocked after many passes, and the pass reports only `skills:blocked` or `native_harness:source_not_successful`, or reports nothing for run logs > - Operators cannot see why, so they cannot tell recoverable data from data that needs a maintenance step > - This pull request recovers the cases that are safe to recover online and gives every other case a precise code > - The benefit is fewer blocked moves and a clear next step for each one that stays blocked ## Linked Issues or Issue Description Refs #19719 **What happened?** A serving server that runs the online durable-data pass many times stays ineligible. The pass reports `skills:blocked` without a reason, `native_harness:source_not_successful` for several different causes, and no reason at all for run logs that stay on the local disk. **Expected behavior** The pass moves every item that it can move safely while the server serves work. For each item that stays, the pass reports a code that names the cause. **Steps to reproduce** 1. Install a catalog skill on a volume-backed server. Remove its installed files and do not keep a saved version. 2. Keep a settled native run whose local log file has no final size or digest and whose events do not prove full coverage. 3. Run the online durable-data pass. 4. See that the skill is reported only as `skills:blocked` and the run log stays local with no reason in the pass result. **Additional context** The settled native log archive path from #19719 had no online caller. ## What Changed - Skill installation conversion returns a `code` for each blocked installation (for example `source_files_unavailable`, `saved_version_incomplete`, `catalog_origin_unavailable`, `legacy_source_unsafe`, `source_changed`). The pass reports `skills:<code>`. An unknown cause stays `skills:blocked`. - A spent budget during conversion now stops the page. Before, it was reported as a blocked skill and the page moved past it. - A catalog skill whose files are gone converts from the bundled catalog package only when the catalog content hash equals the recorded origin hash and the last audit recorded the installed bytes as equal to that origin with no local changes. - A modified catalog skill whose reset origin is gone gets its origin version from the bundled catalog package only when the catalog content hash equals the recorded origin hash. - Native harness pre-copy replaces `source_not_successful` with `source_run_active`, `source_run_unfinished`, `source_coordinator_missing`, `source_coordinator_unsettled`, `source_session_not_selected` and `source_lease_missing`. The settled-source rules do not change. - The run evidence worker archives a settled native log by run id when the canonical import cannot prove event coverage. The existing settled-source guard still decides. The worker records the reasons from its last completed sweep, and the pass reports them as `run_logs:<code>` and `provider_traces:<code>`. - `migrateRunEvidence` accepts a `runId` filter. ## Verification - `cd server && npx vitest run src/__tests__/managed-skill-content.test.ts` (embedded PostgreSQL): new catalog recovery, hash mismatch, unproven install and budget abort tests fail before the change and pass after it. - `npx vitest run src/services/native-runtime/native-harness-online-preservation.integration.test.ts src/services/native-runtime/native-harness-backup-storage.integration.test.ts`: the new reason tests fail before the change and pass after it. - `npx vitest run src/__tests__/run-evidence-migration-work.test.ts src/services/native-log-archive.integration.test.ts`: the worker archive test fails before the change and passes after it. The integration test shows a real settled source that is blocked as `native_log_source_coverage_unproven` and then archived by run id. - `npx vitest run src/services/online-durable-data-migration.test.ts src/services/online-durable-data-migration-postgres.test.ts` - `pnpm --filter @paperclipai/server typecheck` ## Risks - A settled native log with unproven coverage now moves to the read-only historical archive instead of staying local. The archive keeps the exact bytes. It does not claim canonical event coverage. This is the same result that the offline path gives. - The catalog fallback reads bundled or pinned catalog bytes. Each file is checked against its pinned SHA-256, and the package must match the recorded origin hash. - Pass deferral codes change. Readers that match `native_harness:source_not_successful` must use the new codes. > 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`), Anthropic, with tool use and code execution in Claude Code. ## 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>
375 lines
13 KiB
TypeScript
375 lines
13 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
import { existsSync, readFileSync, statSync } from "node:fs";
|
|
import { promises as fs } from "node:fs";
|
|
import { createRequire } from "node:module";
|
|
import path from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import type {
|
|
CatalogSkill,
|
|
CatalogSkillFileDetail,
|
|
CatalogSkillListQuery,
|
|
CatalogSkillSource,
|
|
} from "@paperclipai/shared";
|
|
import { HttpError, conflict, notFound, unprocessable } from "../errors.js";
|
|
import { logger } from "../middleware/logger.js";
|
|
import { ghFetch, resolveRawGitHubUrl } from "./github-fetch.js";
|
|
import { normalizePortablePath } from "./portable-path.js";
|
|
|
|
interface CatalogManifestFile {
|
|
packageName: string;
|
|
packageVersion: string;
|
|
skills: CatalogSkill[];
|
|
}
|
|
|
|
const serviceDir = path.dirname(fileURLToPath(import.meta.url));
|
|
const repoRoot = path.resolve(serviceDir, "../../..");
|
|
const require = createRequire(import.meta.url);
|
|
const catalogPackageName = "@paperclipai/skills-catalog";
|
|
const catalogPackageJsonSpecifier = `${catalogPackageName}/package.json`;
|
|
const catalogManifestSpecifier = `${catalogPackageName}/catalog.json`;
|
|
const devCatalogPackageRoot = path.join(repoRoot, "packages/skills-catalog");
|
|
const devCatalogManifestPath = path.join(devCatalogPackageRoot, "generated/catalog.json");
|
|
let cachedCatalogManifest: {
|
|
manifest: CatalogManifestFile;
|
|
mtimeMs: number;
|
|
size: number;
|
|
} | null = null;
|
|
let cachedCatalogPaths:
|
|
| {
|
|
packageRoot: string;
|
|
manifestPath: string;
|
|
}
|
|
| false
|
|
| null = null;
|
|
let cachedCatalogPathsError: CatalogManifestUnavailableError | null = null;
|
|
let loggedCatalogUnavailableWarning = false;
|
|
|
|
export class CatalogManifestUnavailableError extends Error {
|
|
constructor(message: string, options?: { cause?: unknown }) {
|
|
super(message);
|
|
this.name = "CatalogManifestUnavailableError";
|
|
if (options && "cause" in options) {
|
|
Object.defineProperty(this, "cause", {
|
|
value: options.cause,
|
|
enumerable: false,
|
|
configurable: true,
|
|
writable: true,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
export function isCatalogManifestUnavailableError(error: unknown): error is CatalogManifestUnavailableError {
|
|
return error instanceof CatalogManifestUnavailableError;
|
|
}
|
|
|
|
function manifestUnavailableMessage(manifestPath: string) {
|
|
return `Skills catalog manifest not found at ${manifestPath}. Run pnpm --filter @paperclipai/skills-catalog build:manifest.`;
|
|
}
|
|
|
|
function packageResolutionFailureMessage() {
|
|
return `Skills catalog package could not be resolved from ${catalogPackageJsonSpecifier} and ${catalogManifestSpecifier}.`;
|
|
}
|
|
|
|
function isMissingFileError(error: unknown): error is NodeJS.ErrnoException {
|
|
return error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
|
|
}
|
|
|
|
function resolvePublishedCatalogPaths() {
|
|
return {
|
|
packageRoot: path.dirname(require.resolve(catalogPackageJsonSpecifier)),
|
|
manifestPath: require.resolve(catalogManifestSpecifier),
|
|
};
|
|
}
|
|
|
|
function resolveDevCatalogPaths() {
|
|
if (!existsSync(devCatalogManifestPath)) return null;
|
|
return {
|
|
packageRoot: devCatalogPackageRoot,
|
|
manifestPath: devCatalogManifestPath,
|
|
};
|
|
}
|
|
|
|
function resolveCatalogPaths() {
|
|
if (cachedCatalogPaths === false && cachedCatalogPathsError) {
|
|
throw cachedCatalogPathsError;
|
|
}
|
|
if (cachedCatalogPaths) {
|
|
return cachedCatalogPaths;
|
|
}
|
|
try {
|
|
cachedCatalogPaths = resolvePublishedCatalogPaths();
|
|
cachedCatalogPathsError = null;
|
|
return cachedCatalogPaths;
|
|
} catch (publishedError) {
|
|
const devPaths = resolveDevCatalogPaths();
|
|
if (devPaths) {
|
|
cachedCatalogPaths = devPaths;
|
|
cachedCatalogPathsError = null;
|
|
return cachedCatalogPaths;
|
|
}
|
|
cachedCatalogPathsError = new CatalogManifestUnavailableError(packageResolutionFailureMessage(), { cause: publishedError });
|
|
cachedCatalogPaths = false;
|
|
throw cachedCatalogPathsError;
|
|
}
|
|
}
|
|
|
|
function loadCatalogManifest(manifestPath: string): CatalogManifestFile {
|
|
try {
|
|
return JSON.parse(readFileSync(manifestPath, "utf8")) as CatalogManifestFile;
|
|
} catch (error) {
|
|
if (isMissingFileError(error)) {
|
|
throw new CatalogManifestUnavailableError(manifestUnavailableMessage(manifestPath), { cause: error });
|
|
}
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
function getCatalogManifest() {
|
|
const { manifestPath } = resolveCatalogPaths();
|
|
if (!existsSync(manifestPath)) {
|
|
throw new CatalogManifestUnavailableError(manifestUnavailableMessage(manifestPath));
|
|
}
|
|
let stats: ReturnType<typeof statSync>;
|
|
try {
|
|
stats = statSync(manifestPath);
|
|
} catch (error) {
|
|
if (isMissingFileError(error)) {
|
|
throw new CatalogManifestUnavailableError(manifestUnavailableMessage(manifestPath), { cause: error });
|
|
}
|
|
throw error;
|
|
}
|
|
if (
|
|
cachedCatalogManifest &&
|
|
cachedCatalogManifest.mtimeMs === stats.mtimeMs &&
|
|
cachedCatalogManifest.size === stats.size
|
|
) {
|
|
return cachedCatalogManifest.manifest;
|
|
}
|
|
|
|
const manifest = loadCatalogManifest(manifestPath);
|
|
cachedCatalogManifest = {
|
|
manifest,
|
|
mtimeMs: stats.mtimeMs,
|
|
size: stats.size,
|
|
};
|
|
return manifest;
|
|
}
|
|
|
|
function getCatalogSkills() {
|
|
const catalogManifest = getCatalogManifest();
|
|
return catalogManifest.skills.map((skill) => ({
|
|
...skill,
|
|
packageName: catalogManifest.packageName,
|
|
packageVersion: catalogManifest.packageVersion,
|
|
}));
|
|
}
|
|
|
|
function isMarkdownPath(filePath: string) {
|
|
const fileName = path.posix.basename(filePath).toLowerCase();
|
|
return fileName === "skill.md" || fileName.endsWith(".md");
|
|
}
|
|
|
|
function inferLanguageFromPath(filePath: string) {
|
|
const fileName = path.posix.basename(filePath).toLowerCase();
|
|
if (fileName === "skill.md" || fileName.endsWith(".md")) return "markdown";
|
|
if (fileName.endsWith(".ts")) return "typescript";
|
|
if (fileName.endsWith(".tsx")) return "tsx";
|
|
if (fileName.endsWith(".js")) return "javascript";
|
|
if (fileName.endsWith(".jsx")) return "jsx";
|
|
if (fileName.endsWith(".json")) return "json";
|
|
if (fileName.endsWith(".yml") || fileName.endsWith(".yaml")) return "yaml";
|
|
if (fileName.endsWith(".sh")) return "bash";
|
|
if (fileName.endsWith(".py")) return "python";
|
|
if (fileName.endsWith(".html")) return "html";
|
|
if (fileName.endsWith(".css")) return "css";
|
|
return null;
|
|
}
|
|
|
|
function resolveCatalogPackageRoot() {
|
|
return resolveCatalogPaths().packageRoot;
|
|
}
|
|
|
|
function sourceRootPath(source: CatalogSkillSource) {
|
|
return source.path ? normalizePortablePath(source.path) : "";
|
|
}
|
|
|
|
function resolveCatalogSourcePath(source: CatalogSkillSource, relativePath: string) {
|
|
const sourceRoot = sourceRootPath(source);
|
|
return sourceRoot ? `${sourceRoot}/${relativePath}` : relativePath;
|
|
}
|
|
|
|
async function fetchCatalogSourceFile(
|
|
skill: CatalogSkill,
|
|
relativePath: string,
|
|
signal?: AbortSignal,
|
|
): Promise<Buffer> {
|
|
const source = skill.source;
|
|
if (!source) {
|
|
const packageRoot = resolveCatalogPackageRoot();
|
|
const absolutePath = path.resolve(packageRoot, skill.path, relativePath);
|
|
const skillRoot = path.resolve(packageRoot, skill.path);
|
|
if (absolutePath !== skillRoot && !absolutePath.startsWith(`${skillRoot}${path.sep}`)) {
|
|
throw notFound("Catalog skill file not found");
|
|
}
|
|
return fs.readFile(absolutePath);
|
|
}
|
|
|
|
if (source.type !== "github") {
|
|
throw unprocessable(`Unsupported catalog source type: ${(source as { type: string }).type}`);
|
|
}
|
|
|
|
const sourcePath = resolveCatalogSourcePath(source, relativePath);
|
|
const url = resolveRawGitHubUrl(source.hostname, source.owner, source.repo, source.commit, sourcePath);
|
|
const response = await ghFetch(url, signal ? { signal } : undefined);
|
|
if (!response.ok) {
|
|
throw unprocessable(`Failed to fetch pinned catalog file ${sourcePath} from ${source.owner}/${source.repo}@${source.commit}: HTTP ${response.status}`);
|
|
}
|
|
return Buffer.from(await response.arrayBuffer());
|
|
}
|
|
|
|
async function readCatalogFileBytes(
|
|
skill: CatalogSkill,
|
|
relativePath: string,
|
|
signal?: AbortSignal,
|
|
): Promise<Buffer> {
|
|
const fileEntry = skill.files.find((entry) => entry.path === relativePath);
|
|
if (!fileEntry) {
|
|
throw notFound("Catalog skill file not found");
|
|
}
|
|
|
|
const bytes = await fetchCatalogSourceFile(skill, relativePath, signal);
|
|
const actualSha = createHash("sha256").update(bytes).digest("hex");
|
|
if (actualSha !== fileEntry.sha256) {
|
|
throw unprocessable(`Pinned catalog file hash mismatch for ${skill.id}:${relativePath}.`);
|
|
}
|
|
return bytes;
|
|
}
|
|
|
|
function searchText(skill: CatalogSkill) {
|
|
return [
|
|
skill.id,
|
|
skill.key,
|
|
skill.slug,
|
|
skill.name,
|
|
skill.description,
|
|
skill.category,
|
|
skill.kind,
|
|
...skill.recommendedForRoles,
|
|
...skill.tags,
|
|
].join("\n").toLowerCase();
|
|
}
|
|
|
|
export function listCatalogSkills(query: CatalogSkillListQuery = {}): CatalogSkill[] {
|
|
const normalizedQuery = query.q?.trim().toLowerCase() ?? "";
|
|
return getCatalogSkills()
|
|
.filter((skill) => !query.kind || skill.kind === query.kind)
|
|
.filter((skill) => !query.category || skill.category === query.category)
|
|
.filter((skill) => !normalizedQuery || searchText(skill).includes(normalizedQuery))
|
|
.sort((left, right) => left.name.localeCompare(right.name) || left.key.localeCompare(right.key));
|
|
}
|
|
|
|
export function listCatalogSkillsOrEmpty(query: CatalogSkillListQuery = {}): CatalogSkill[] {
|
|
try {
|
|
const skills = listCatalogSkills(query);
|
|
loggedCatalogUnavailableWarning = false;
|
|
return skills;
|
|
} catch (error) {
|
|
if (!isCatalogManifestUnavailableError(error)) {
|
|
throw error;
|
|
}
|
|
if (!loggedCatalogUnavailableWarning) {
|
|
logger.warn({ err: error }, "skills catalog manifest unavailable; returning empty catalog");
|
|
loggedCatalogUnavailableWarning = true;
|
|
}
|
|
return [];
|
|
}
|
|
}
|
|
|
|
export function resolveCatalogSkillReference(reference: string): { skill: CatalogSkill | null; ambiguous: boolean } {
|
|
const trimmed = reference.trim();
|
|
if (!trimmed) return { skill: null, ambiguous: false };
|
|
const catalogSkills = getCatalogSkills();
|
|
|
|
const exact = catalogSkills.find((skill) => skill.id === trimmed || skill.key === trimmed);
|
|
if (exact) return { skill: exact, ambiguous: false };
|
|
|
|
const slugMatches = catalogSkills.filter((skill) => skill.slug === trimmed);
|
|
if (slugMatches.length === 1) return { skill: slugMatches[0]!, ambiguous: false };
|
|
if (slugMatches.length > 1) return { skill: null, ambiguous: true };
|
|
return { skill: null, ambiguous: false };
|
|
}
|
|
|
|
export function getCatalogSkillOrThrow(reference: string): CatalogSkill {
|
|
const result = resolveCatalogSkillReference(reference);
|
|
if (result.ambiguous) {
|
|
throw conflict(`Catalog skill slug "${reference}" is ambiguous. Use an id or key.`);
|
|
}
|
|
if (!result.skill) {
|
|
throw notFound("Catalog skill not found");
|
|
}
|
|
return result.skill;
|
|
}
|
|
|
|
export async function readCatalogSkillFile(
|
|
reference: string,
|
|
relativePath = "SKILL.md",
|
|
): Promise<CatalogSkillFileDetail> {
|
|
const skill = getCatalogSkillOrThrow(reference);
|
|
const normalizedPath = normalizePortablePath(relativePath || "SKILL.md");
|
|
const fileEntry = skill.files.find((entry) => entry.path === normalizedPath);
|
|
if (!fileEntry) {
|
|
throw notFound("Catalog skill file not found");
|
|
}
|
|
|
|
if (fileEntry.kind === "asset") {
|
|
throw new HttpError(415, "Catalog asset previews are not supported.");
|
|
}
|
|
|
|
const content = (await readCatalogFileBytes(skill, normalizedPath)).toString("utf8");
|
|
return {
|
|
catalogSkillId: skill.id,
|
|
path: normalizedPath,
|
|
kind: fileEntry.kind,
|
|
content,
|
|
language: inferLanguageFromPath(normalizedPath),
|
|
markdown: isMarkdownPath(normalizedPath),
|
|
};
|
|
}
|
|
|
|
export async function copyCatalogSkillFile(reference: string, relativePath: string, targetPath: string): Promise<void> {
|
|
const skill = getCatalogSkillOrThrow(reference);
|
|
const normalizedPath = normalizePortablePath(relativePath || "SKILL.md");
|
|
const fileEntry = skill.files.find((entry) => entry.path === normalizedPath);
|
|
if (!fileEntry) {
|
|
throw notFound("Catalog skill file not found");
|
|
}
|
|
|
|
await fs.writeFile(targetPath, await readCatalogFileBytes(skill, normalizedPath));
|
|
}
|
|
|
|
export async function readPinnedCatalogSkillFiles(reference: string, contentHash: string, signal?: AbortSignal) {
|
|
let skill: CatalogSkill | null;
|
|
try { skill = resolveCatalogSkillReference(reference).skill; }
|
|
catch (error) {
|
|
if (isCatalogManifestUnavailableError(error)) return null;
|
|
throw error;
|
|
}
|
|
if (!skill || skill.contentHash !== contentHash) return null;
|
|
const pinned = skill;
|
|
const files: Array<{ path: string; bytes: Buffer }> = [];
|
|
for (const entry of pinned.files) {
|
|
signal?.throwIfAborted();
|
|
files.push({ path: entry.path, bytes: await readCatalogFileBytes(pinned, entry.path, signal) });
|
|
}
|
|
return files;
|
|
}
|
|
|
|
export function getCatalogPackageMetadata() {
|
|
const catalogManifest = getCatalogManifest();
|
|
return {
|
|
packageName: catalogManifest.packageName,
|
|
packageVersion: catalogManifest.packageVersion,
|
|
};
|
|
}
|