Add managed plugin skill contracts

Co-Authored-By: Paperclip <noreply@paperclip.ing>

server/src/__tests__/plugin-managed-skills.test.ts

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  activityLog,
+  companies,
+  companySkills,
+  createDb,
+  pluginManagedResources,
+  plugins,
+} from "@paperclipai/db";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { buildHostServices } from "../services/plugin-host-services.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+function createEventBusStub() {
+  return {
+    forPlugin() {
+      return {
+        emit: async () => {},
+        subscribe: () => {},
+      };
+    },
+  } as any;
+}
+
+function issuePrefix(id: string) {
+  return `T${id.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
+}
+
+function manifest(): PaperclipPluginManifestV1 {
+  return {
+    id: "paperclip.managed-skills-test",
+    apiVersion: 1,
+    version: "0.1.0",
+    displayName: "Managed Skills Test",
+    description: "Test plugin",
+    author: "Paperclip",
+    categories: ["automation"],
+    capabilities: ["skills.managed"],
+    entrypoints: { worker: "./dist/worker.js" },
+    skills: [{
+      skillKey: "wiki-maintainer",
+      displayName: "Wiki Maintainer Skill",
+      description: "Use LLM Wiki tools to maintain company knowledge.",
+      files: [{
+        path: "references/wiki-style.md",
+        content: "# Wiki style\n\nKeep pages cited and terse.\n",
+      }],
+    }],
+  };
+}
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres plugin-managed skill tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("plugin-managed skills", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-managed-skills-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(activityLog);
+    await db.delete(pluginManagedResources);
+    await db.delete(companySkills);
+    await db.delete(plugins);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function seedCompanyAndPlugin(pluginManifest = manifest()) {
+    const companyId = randomUUID();
+    const pluginId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: issuePrefix(companyId),
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: pluginManifest.id,
+      packageName: "@paperclipai/plugin-managed-skills-test",
+      version: pluginManifest.version,
+      apiVersion: pluginManifest.apiVersion,
+      categories: pluginManifest.categories,
+      manifestJson: pluginManifest,
+      status: "ready",
+      installOrder: 1,
+    });
+    const services = buildHostServices(db, pluginId, pluginManifest.id, createEventBusStub(), undefined, {
+      manifest: pluginManifest,
+    });
+    return { companyId, pluginId, pluginManifest, services };
+  }
+
+  it("installs and resolves managed company skills by stable resource key", async () => {
+    const { companyId, services } = await seedCompanyAndPlugin();
+
+    const created = await services.skills.managedReconcile({
+      companyId,
+      skillKey: "wiki-maintainer",
+    });
+
+    expect(created.status).toBe("created");
+    expect(created.skill).toMatchObject({
+      name: "Wiki Maintainer Skill",
+      key: "plugin/paperclip-managed-skills-test/wiki-maintainer",
+      sourceType: "catalog",
+      fileInventory: expect.arrayContaining([
+        expect.objectContaining({ path: "SKILL.md", kind: "skill" }),
+        expect.objectContaining({ path: "references/wiki-style.md", kind: "reference" }),
+      ]),
+    });
+
+    const resolved = await services.skills.managedGet({
+      companyId,
+      skillKey: "wiki-maintainer",
+    });
+    expect(resolved.status).toBe("resolved");
+    expect(resolved.skillId).toBe(created.skillId);
+
+    const [binding] = await db.select().from(pluginManagedResources);
+    expect(binding).toMatchObject({
+      companyId,
+      resourceKind: "skill",
+      resourceKey: "wiki-maintainer",
+      resourceId: created.skillId,
+    });
+  });
+
+  it("preserves operator edits during reconcile and restores manifest defaults on reset", async () => {
+    const { companyId, services } = await seedCompanyAndPlugin();
+    const created = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+    expect(created.skillId).toBeTruthy();
+
+    await db
+      .update(companySkills)
+      .set({
+        name: "Custom Wiki Skill",
+        markdown: "# Custom instructions\n",
+        updatedAt: new Date(),
+      })
+      .where(eq(companySkills.id, created.skillId!));
+
+    const reconciled = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+    expect(reconciled.status).toBe("resolved");
+    expect(reconciled.skill).toMatchObject({
+      name: "Custom Wiki Skill",
+      markdown: "# Custom instructions\n",
+    });
+
+    const reset = await services.skills.managedReset({ companyId, skillKey: "wiki-maintainer" });
+    expect(reset.status).toBe("reset");
+    expect(reset.skill).toMatchObject({
+      name: "Wiki Maintainer Skill",
+      description: "Use LLM Wiki tools to maintain company knowledge.",
+    });
+    expect(reset.skill?.markdown).toContain("key: \"plugin/paperclip-managed-skills-test/wiki-maintainer\"");
+  });
+
+  it("adds the canonical managed key to manifest-provided markdown skills", async () => {
+    const pluginManifest = manifest();
+    pluginManifest.skills = [
+      ...(pluginManifest.skills ?? []),
+      {
+        skillKey: "markdown-skill",
+        displayName: "Markdown Skill",
+        markdown: [
+          "---",
+          "name: markdown-skill",
+          "description: Markdown source without a key.",
+          "---",
+          "",
+          "# Markdown Skill",
+          "",
+          "Follow the managed markdown.",
+        ].join("\n"),
+      },
+    ];
+    const { companyId, services } = await seedCompanyAndPlugin(pluginManifest);
+
+    const created = await services.skills.managedReconcile({ companyId, skillKey: "markdown-skill" });
+
+    expect(created.status).toBe("created");
+    expect(created.skill).toMatchObject({
+      key: "plugin/paperclip-managed-skills-test/markdown-skill",
+      name: "markdown-skill",
+    });
+    expect(created.skill?.markdown).toContain("key: \"plugin/paperclip-managed-skills-test/markdown-skill\"");
+  });
+});

server/src/services/plugin-host-services.ts

@@ -44,6 +44,7 @@ import { pluginStateStore } from "./plugin-state-store.js";
 import { pluginDatabaseService } from "./plugin-database.js";
 import { pluginManagedAgentService } from "./plugin-managed-agents.js";
 import { pluginManagedRoutineService } from "./plugin-managed-routines.js";
+import { pluginManagedSkillService } from "./plugin-managed-skills.js";
 import {
   assertConfiguredLocalFolder,
   assertWritableConfiguredLocalFolder,
@@ -509,6 +510,11 @@ export function buildHostServices(
     manifest: options.manifest,
     pluginWorkerManager: options.pluginWorkerManager,
   });
+  const managedSkills = pluginManagedSkillService(db, {
+    pluginId,
+    pluginKey,
+    manifest: options.manifest,
+  });
   const heartbeat = heartbeatService(db, {
     pluginWorkerManager: options.pluginWorkerManager,
   });
@@ -1224,6 +1230,24 @@ export function buildHostServices(
       },
     },
 
+    skills: {
+      async managedGet(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return managedSkills.get(params.skillKey, companyId);
+      },
+      async managedReconcile(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return managedSkills.reconcile(params.skillKey, companyId);
+      },
+      async managedReset(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return managedSkills.reset(params.skillKey, companyId);
+      },
+    },
+
     issues: {
       async list(params) {
         const companyId = ensureCompanyId(params.companyId);

server/src/services/plugin-managed-agents.ts

@@ -126,6 +126,33 @@ function applyInstructionTemplateVariables(
   return next;
 }
 
+function declaredInstructionFiles(
+  declaration: PluginManagedAgentDeclaration,
+  variables: Record<string, string | null | undefined>,
+) {
+  const instructionDeclaration = declaration.instructions;
+  if (!instructionDeclaration?.content && !instructionDeclaration?.files) return null;
+
+  const entryFile = instructionDeclaration.entryFile ?? "AGENTS.md";
+  const files = { ...(instructionDeclaration.files ?? {}) };
+  if (instructionDeclaration.content !== undefined) {
+    files[entryFile] = instructionDeclaration.content;
+  }
+  if (files[entryFile] === undefined) {
+    files[entryFile] = "";
+  }
+
+  return {
+    entryFile,
+    files: Object.fromEntries(
+      Object.entries(files).map(([filePath, content]) => [
+        filePath,
+        applyInstructionTemplateVariables(content, variables),
+      ]),
+    ),
+  };
+}
+
 function rowIsManagedAgent(
   row: typeof agents.$inferSelect,
   pluginKey: string,
@@ -299,19 +326,18 @@ export function pluginManagedAgentService(
     companyId: string,
     agent: Agent,
     declaration: PluginManagedAgentDeclaration,
-    options: { replaceExisting: boolean },
+    materializeOptions: { replaceExisting: boolean },
   ): Promise<Agent> {
-    const instructionDeclaration = declaration.instructions;
-    if (!instructionDeclaration?.content) return agent;
-
-    const entryFile = instructionDeclaration.entryFile ?? "AGENTS.md";
     const variables = await optionsForInstructionVariables(companyId);
+    const declared = declaredInstructionFiles(declaration, variables);
+    if (!declared) return agent;
+
     const materialized = await instructions.materializeManagedBundle(
       agent,
-      { [entryFile]: applyInstructionTemplateVariables(instructionDeclaration.content, variables) },
+      declared.files,
       {
-        entryFile,
-        replaceExisting: options.replaceExisting,
+        entryFile: declared.entryFile,
+        replaceExisting: materializeOptions.replaceExisting,
         clearLegacyPromptTemplate: true,
       },
     );
@@ -325,6 +351,33 @@ export function pluginManagedAgentService(
     return (updated as Agent | null) ?? { ...agent, adapterConfig: materialized.adapterConfig };
   }
 
+  async function managedInstructionDefaultDrift(
+    companyId: string,
+    agent: Agent | null,
+    declaration: PluginManagedAgentDeclaration,
+  ): Promise<PluginManagedAgentResolution["defaultDrift"]> {
+    if (!agent) return null;
+    const variables = await optionsForInstructionVariables(companyId);
+    const declared = declaredInstructionFiles(declaration, variables);
+    if (!declared) return null;
+
+    let exported: Awaited<ReturnType<typeof instructions.exportFiles>>;
+    try {
+      exported = await instructions.exportFiles(agent);
+    } catch {
+      return { entryFile: declared.entryFile, changedFiles: [declared.entryFile] };
+    }
+
+    const paths = new Set([...Object.keys(declared.files), ...Object.keys(exported.files)]);
+    const changedFiles = [...paths]
+      .filter((filePath) => (exported.files[filePath] ?? null) !== (declared.files[filePath] ?? null))
+      .sort((left, right) => left.localeCompare(right));
+    if (exported.entryFile !== declared.entryFile && !changedFiles.includes(declared.entryFile)) {
+      changedFiles.unshift(declared.entryFile);
+    }
+    return changedFiles.length > 0 ? { entryFile: declared.entryFile, changedFiles } : null;
+  }
+
   async function optionsForInstructionVariables(companyId: string) {
     return options.instructionTemplateVariables ? options.instructionTemplateVariables(companyId) : {};
   }
@@ -333,13 +386,13 @@ export function pluginManagedAgentService(
     return options.pluginKey;
   }
 
-  function resolution(
+  async function resolution(
     companyId: string,
     declaration: PluginManagedAgentDeclaration,
     agent: Agent | null,
     status: PluginManagedAgentResolution["status"],
     approvalId?: string | null,
-  ): PluginManagedAgentResolution {
+  ): Promise<PluginManagedAgentResolution> {
     return {
       pluginKey: options.pluginKey,
       resourceKind: "agent",
@@ -349,6 +402,7 @@ export function pluginManagedAgentService(
       agent,
       status,
       approvalId: approvalId ?? null,
+      defaultDrift: await managedInstructionDefaultDrift(companyId, agent, declaration),
     };
   }
 

server/src/services/plugin-managed-skills.ts

@@ -0,0 +1,279 @@
+import { and, eq } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  pluginManagedResources,
+} from "@paperclipai/db";
+import { normalizeAgentUrlKey } from "@paperclipai/shared";
+import type {
+  CompanySkill,
+  PaperclipPluginManifestV1,
+  PluginManagedSkillDeclaration,
+  PluginManagedSkillResolution,
+} from "@paperclipai/shared";
+import { notFound } from "../errors.js";
+import { logActivity } from "./activity-log.js";
+import { companySkillService } from "./company-skills.js";
+
+const MANAGED_SKILL_RESOURCE_KIND = "skill";
+
+interface PluginManagedSkillServiceOptions {
+  pluginId: string;
+  pluginKey: string;
+  manifest?: PaperclipPluginManifestV1 | null;
+}
+
+function pluginKeySlug(pluginKey: string) {
+  return normalizeAgentUrlKey(pluginKey) ?? "plugin";
+}
+
+function canonicalSkillKey(pluginKey: string, skillKey: string) {
+  return `plugin/${pluginKeySlug(pluginKey)}/${skillKey}`;
+}
+
+function yamlString(value: string) {
+  return JSON.stringify(value);
+}
+
+function buildDefaultMarkdown(
+  pluginKey: string,
+  declaration: PluginManagedSkillDeclaration,
+) {
+  const description = declaration.description?.trim() || `${declaration.displayName} plugin skill.`;
+  return [
+    "---",
+    `name: ${yamlString(declaration.displayName)}`,
+    `description: ${yamlString(description)}`,
+    `key: ${yamlString(canonicalSkillKey(pluginKey, declaration.skillKey))}`,
+    "---",
+    "",
+    `# ${declaration.displayName}`,
+    "",
+    description,
+    "",
+  ].join("\n");
+}
+
+function withManagedSkillKey(markdown: string, canonicalKey: string) {
+  const keyLine = `key: ${yamlString(canonicalKey)}`;
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  const frontmatter = /^---\n([\s\S]*?)\n---(\n?)/.exec(normalized);
+  if (!frontmatter) {
+    return [
+      "---",
+      keyLine,
+      "---",
+      "",
+      normalized,
+    ].join("\n");
+  }
+
+  const currentBody = frontmatter[1] ?? "";
+  const nextBody = /^key\s*:/m.test(currentBody)
+    ? currentBody.replace(/^key\s*:.*$/m, keyLine)
+    : [currentBody, keyLine].filter(Boolean).join("\n");
+  return `---\n${nextBody}\n---${frontmatter[2] ?? ""}${normalized.slice(frontmatter[0].length)}`;
+}
+
+function buildPackageFiles(
+  pluginKey: string,
+  declaration: PluginManagedSkillDeclaration,
+) {
+  const root = declaration.skillKey;
+  const canonicalKey = canonicalSkillKey(pluginKey, declaration.skillKey);
+  const files: Record<string, string> = {
+    [`${root}/SKILL.md`]: declaration.markdown?.trim()
+      ? withManagedSkillKey(declaration.markdown, canonicalKey)
+      : buildDefaultMarkdown(pluginKey, declaration),
+  };
+  for (const file of declaration.files ?? []) {
+    files[`${root}/${file.path}`] = file.content;
+  }
+  return files;
+}
+
+function buildSkillDefaults(
+  pluginKey: string,
+  declaration: PluginManagedSkillDeclaration,
+) {
+  return {
+    skillKey: declaration.skillKey,
+    displayName: declaration.displayName,
+    slug: declaration.slug ?? declaration.skillKey,
+    description: declaration.description ?? null,
+    canonicalKey: canonicalSkillKey(pluginKey, declaration.skillKey),
+    files: [
+      "SKILL.md",
+      ...(declaration.files ?? []).map((file) => file.path),
+    ],
+  };
+}
+
+function resolution(
+  pluginKey: string,
+  companyId: string,
+  declaration: PluginManagedSkillDeclaration,
+  skill: CompanySkill | null,
+  status: PluginManagedSkillResolution["status"],
+): PluginManagedSkillResolution {
+  return {
+    pluginKey,
+    resourceKind: "skill",
+    resourceKey: declaration.skillKey,
+    companyId,
+    skillId: skill?.id ?? null,
+    skill,
+    status,
+  };
+}
+
+export function pluginManagedSkillService(
+  db: Db,
+  options: PluginManagedSkillServiceOptions,
+) {
+  const skills = companySkillService(db);
+
+  function declarationFor(skillKey: string) {
+    const declaration = options.manifest?.skills?.find((skill) => skill.skillKey === skillKey);
+    if (!declaration) {
+      throw notFound(`Managed skill declaration not found: ${skillKey}`);
+    }
+    return declaration;
+  }
+
+  async function getBinding(companyId: string, skillKey: string) {
+    return db
+      .select()
+      .from(pluginManagedResources)
+      .where(and(
+        eq(pluginManagedResources.companyId, companyId),
+        eq(pluginManagedResources.pluginId, options.pluginId),
+        eq(pluginManagedResources.resourceKind, MANAGED_SKILL_RESOURCE_KIND),
+        eq(pluginManagedResources.resourceKey, skillKey),
+      ))
+      .then((rows) => rows[0] ?? null);
+  }
+
+  async function upsertBinding(
+    companyId: string,
+    declaration: PluginManagedSkillDeclaration,
+    skillId: string,
+  ) {
+    const defaultsJson = buildSkillDefaults(options.pluginKey, declaration);
+    const existing = await getBinding(companyId, declaration.skillKey);
+    if (existing) {
+      return db
+        .update(pluginManagedResources)
+        .set({
+          resourceId: skillId,
+          defaultsJson,
+          updatedAt: new Date(),
+        })
+        .where(eq(pluginManagedResources.id, existing.id))
+        .returning()
+        .then((rows) => rows[0]);
+    }
+    return db
+      .insert(pluginManagedResources)
+      .values({
+        companyId,
+        pluginId: options.pluginId,
+        pluginKey: options.pluginKey,
+        resourceKind: MANAGED_SKILL_RESOURCE_KIND,
+        resourceKey: declaration.skillKey,
+        resourceId: skillId,
+        defaultsJson,
+      })
+      .returning()
+      .then((rows) => rows[0]);
+  }
+
+  async function getSkill(companyId: string, skillId: string) {
+    return skills.getById(companyId, skillId);
+  }
+
+  async function importDeclaredSkill(
+    companyId: string,
+    declaration: PluginManagedSkillDeclaration,
+    mode: "reconcile" | "reset",
+  ) {
+    const beforeByKey = mode === "reconcile"
+      ? await skills.getByKey(companyId, canonicalSkillKey(options.pluginKey, declaration.skillKey))
+      : null;
+    const results = await skills.importPackageFiles(
+      companyId,
+      buildPackageFiles(options.pluginKey, declaration),
+      { onConflict: "replace" },
+    );
+    const imported = results.find((result) =>
+      result.skill.key === canonicalSkillKey(options.pluginKey, declaration.skillKey)
+      || result.originalSlug === (declaration.slug ?? declaration.skillKey)
+      || result.originalSlug === declaration.skillKey
+    )?.skill ?? results[0]?.skill ?? null;
+    if (!imported) {
+      throw notFound(`Managed skill was not imported: ${declaration.skillKey}`);
+    }
+    await upsertBinding(companyId, declaration, imported.id);
+    const status: PluginManagedSkillResolution["status"] = mode === "reset"
+      ? "reset"
+      : beforeByKey
+        ? "relinked"
+        : "created";
+    return { skill: imported, status };
+  }
+
+  async function get(skillKey: string, companyId: string) {
+    const declaration = declarationFor(skillKey);
+    const binding = await getBinding(companyId, skillKey);
+    if (!binding) return resolution(options.pluginKey, companyId, declaration, null, "missing");
+    const skill = await getSkill(companyId, binding.resourceId);
+    return resolution(options.pluginKey, companyId, declaration, skill, skill ? "resolved" : "missing");
+  }
+
+  async function reconcile(skillKey: string, companyId: string) {
+    const declaration = declarationFor(skillKey);
+    const current = await get(skillKey, companyId);
+    if (current.skill) {
+      await upsertBinding(companyId, declaration, current.skill.id);
+      return current;
+    }
+    const imported = await importDeclaredSkill(companyId, declaration, "reconcile");
+    await logActivity(db, {
+      companyId,
+      actorType: "plugin",
+      actorId: options.pluginId,
+      action: "plugin.managed_skill.reconciled",
+      entityType: "company_skill",
+      entityId: imported.skill.id,
+      details: {
+        sourcePluginKey: options.pluginKey,
+        managedResourceKey: declaration.skillKey,
+        status: imported.status,
+      },
+    });
+    return resolution(options.pluginKey, companyId, declaration, imported.skill, imported.status);
+  }
+
+  async function reset(skillKey: string, companyId: string) {
+    const declaration = declarationFor(skillKey);
+    const imported = await importDeclaredSkill(companyId, declaration, "reset");
+    await logActivity(db, {
+      companyId,
+      actorType: "plugin",
+      actorId: options.pluginId,
+      action: "plugin.managed_skill.reset",
+      entityType: "company_skill",
+      entityId: imported.skill.id,
+      details: {
+        sourcePluginKey: options.pluginKey,
+        managedResourceKey: declaration.skillKey,
+      },
+    });
+    return resolution(options.pluginKey, companyId, declaration, imported.skill, "reset");
+  }
+
+  return {
+    get,
+    reconcile,
+    reset,
+  };
+}