fix: harden heartbeat and adapter runtime workflows

2026-04-10 22:26:21 -05:00
parent 548721248e
commit c566a9236c
48 changed files with 14922 additions and 600 deletions
@@ -0,0 +1,172 @@
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createHash, type Hash } from "node:crypto";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { ensurePaperclipSkillSymlink, type PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils";
+
+const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+
+type SkillEntry = PaperclipSkillEntry;
+
+export interface ClaudePromptBundle {
+  bundleKey: string;
+  rootDir: string;
+  addDir: string;
+  instructionsFilePath: string | null;
+}
+
+function nonEmpty(value: string | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveManagedClaudePromptCacheRoot(
+  env: NodeJS.ProcessEnv,
+  companyId: string,
+): string {
+  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
+  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  return path.resolve(
+    paperclipHome,
+    "instances",
+    instanceId,
+    "companies",
+    companyId,
+    "claude-prompt-cache",
+  );
+}
+
+async function hashPathContents(
+  candidate: string,
+  hash: Hash,
+  relativePath: string,
+  seenDirectories: Set<string>,
+): Promise<void> {
+  const stat = await fs.lstat(candidate);
+
+  if (stat.isSymbolicLink()) {
+    hash.update(`symlink:${relativePath}\n`);
+    const resolved = await fs.realpath(candidate).catch(() => null);
+    if (!resolved) {
+      hash.update("missing\n");
+      return;
+    }
+    await hashPathContents(resolved, hash, relativePath, seenDirectories);
+    return;
+  }
+
+  if (stat.isDirectory()) {
+    const realDir = await fs.realpath(candidate).catch(() => candidate);
+    hash.update(`dir:${relativePath}\n`);
+    if (seenDirectories.has(realDir)) {
+      hash.update("loop\n");
+      return;
+    }
+    seenDirectories.add(realDir);
+    const entries = await fs.readdir(candidate, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const childRelativePath = relativePath.length > 0 ? `${relativePath}/${entry.name}` : entry.name;
+      await hashPathContents(path.join(candidate, entry.name), hash, childRelativePath, seenDirectories);
+    }
+    return;
+  }
+
+  if (stat.isFile()) {
+    hash.update(`file:${relativePath}\n`);
+    hash.update(await fs.readFile(candidate));
+    hash.update("\n");
+    return;
+  }
+
+  hash.update(`other:${relativePath}:${stat.mode}\n`);
+}
+
+async function buildClaudePromptBundleKey(input: {
+  skills: SkillEntry[];
+  instructionsContents: string | null;
+}): Promise<string> {
+  const hash = createHash("sha256");
+  hash.update("paperclip-claude-prompt-bundle:v1\n");
+  if (input.instructionsContents) {
+    hash.update("instructions\n");
+    hash.update(input.instructionsContents);
+    hash.update("\n");
+  } else {
+    hash.update("instructions:none\n");
+  }
+
+  const sortedSkills = [...input.skills].sort((left, right) => left.runtimeName.localeCompare(right.runtimeName));
+  for (const entry of sortedSkills) {
+    hash.update(`skill:${entry.key}:${entry.runtimeName}\n`);
+    await hashPathContents(entry.source, hash, entry.runtimeName, new Set<string>());
+  }
+
+  return hash.digest("hex");
+}
+
+async function ensureReadableFile(targetPath: string, contents: string): Promise<void> {
+  try {
+    await fs.access(targetPath, fsConstants.R_OK);
+    return;
+  } catch {
+    // Fall through and materialize the file.
+  }
+
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await fs.writeFile(tempPath, contents, "utf8");
+    await fs.rename(tempPath, targetPath);
+  } catch (err) {
+    const targetReadable = await fs.access(targetPath, fsConstants.R_OK).then(() => true).catch(() => false);
+    if (!targetReadable) {
+      throw err;
+    }
+  } finally {
+    await fs.rm(tempPath, { force: true }).catch(() => {});
+  }
+}
+
+export async function prepareClaudePromptBundle(input: {
+  companyId: string;
+  skills: SkillEntry[];
+  instructionsContents: string | null;
+  onLog: AdapterExecutionContext["onLog"];
+}): Promise<ClaudePromptBundle> {
+  const { companyId, skills, instructionsContents, onLog } = input;
+  const bundleKey = await buildClaudePromptBundleKey({
+    skills,
+    instructionsContents,
+  });
+  const rootDir = path.join(resolveManagedClaudePromptCacheRoot(process.env, companyId), bundleKey);
+  const skillsHome = path.join(rootDir, ".claude", "skills");
+  await fs.mkdir(skillsHome, { recursive: true });
+
+  for (const entry of skills) {
+    const target = path.join(skillsHome, entry.runtimeName);
+    try {
+      await ensurePaperclipSkillSymlink(entry.source, target);
+    } catch (err) {
+      await onLog(
+        "stderr",
+        `[paperclip] Failed to materialize Claude skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    }
+  }
+
+  const instructionsFilePath = instructionsContents
+    ? path.join(rootDir, "agent-instructions.md")
+    : null;
+  if (instructionsFilePath && instructionsContents) {
+    await ensureReadableFile(instructionsFilePath, instructionsContents);
+  }
+
+  return {
+    bundleKey,
+    rootDir,
+    addDir: rootDir,
+    instructionsFilePath,
+  };
+}