The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(skills): add company skill fork prechecks (#9235)
Dotta4a7a732476eb
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex e724fd16b6..f771ed6cf2 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -455,6 +455,11 @@ export type {CompanySkillCommentCreateRequest,CompanySkillCommentUpdateRequest,CompanySkillForkRequest,+ CompanySkillOriginalSummary,+ CompanySkillForkSummary,+ CompanySkillForkReassignment,+ CompanySkillForkResult,+ CompanySkillForkPrecheckResult,CompanySkillUpdateRequest,CompanySkillUpdateStatus,CompanySkillAuditSeverity,diff --git a/packages/shared/src/types/company-skill.ts b/packages/shared/src/types/company-skill.tsindex a2d3e6b9f2..4573ecc816 100644--- a/packages/shared/src/types/company-skill.ts+++ b/packages/shared/src/types/company-skill.ts@@ -111,6 +111,7 @@ export interface CompanySkillUsageAgent {export interface CompanySkillDetail extends CompanySkill {attachedAgentCount: number;usedByAgents: CompanySkillUsageAgent[];+ existingForks: CompanySkillForkSummary[];editable: boolean;editableReason: string | null;sourceLabel: string | null;@@ -180,6 +181,47 @@ export interface CompanySkillForkRequest {name?: string | null;slug?: string | null;sharingScope?: CompanySkillSharingScope;+ reassignAgentIds?: string[];+}++export interface CompanySkillOriginalSummary {+ id: string;+ name: string;+ slug: string;+ sourceType: CompanySkillSourceType;+ sourceLocator: string | null;+ sourceRef: string | null;+}++export interface CompanySkillForkSummary extends CompanySkillOriginalSummary {+ key: string;+ forkedFromSkillId: string | null;+ forkedFromCompanyId: string | null;+ currentVersionId: string | null;+ createdByCurrentActor: boolean;+ diverged: boolean;+ createdAt: Date;+ updatedAt: Date;+}++export interface CompanySkillForkReassignment {+ agentId: string;+ previousSkillKey: string;+ nextSkillKey: string;+}++export interface CompanySkillForkResult {+ skill: CompanySkill;+ original: CompanySkillOriginalSummary;+ reassignments: CompanySkillForkReassignment[];+}++export interface CompanySkillForkPrecheckResult {+ skillId: string;+ original: CompanySkillOriginalSummary;+ agentUsageCount: number;+ usedByAgents: CompanySkillUsageAgent[];+ existingForks: CompanySkillForkSummary[];}export interface CompanySkillUpdateRequest {diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex 0d27034914..c0245d1f84 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -77,6 +77,11 @@ export type {CompanySkillCommentCreateRequest,CompanySkillCommentUpdateRequest,CompanySkillForkRequest,+ CompanySkillOriginalSummary,+ CompanySkillForkSummary,+ CompanySkillForkReassignment,+ CompanySkillForkResult,+ CompanySkillForkPrecheckResult,CompanySkillUpdateRequest,CompanySkillUpdateStatus,CompanySkillAuditSeverity,diff --git a/packages/shared/src/validators/company-skill.ts b/packages/shared/src/validators/company-skill.tsindex ff223dd60f..793f5671a1 100644--- a/packages/shared/src/validators/company-skill.ts+++ b/packages/shared/src/validators/company-skill.ts@@ -73,6 +73,26 @@ export const companySkillUsageAgentSchema = z.object({versionId: z.string().uuid().nullable(),});+export const companySkillOriginalSummarySchema = z.object({+ id: z.string().uuid(),+ name: z.string().min(1),+ slug: z.string().min(1),+ sourceType: companySkillSourceTypeSchema,+ sourceLocator: z.string().nullable(),+ sourceRef: z.string().nullable(),+});++export const companySkillForkSummarySchema = companySkillOriginalSummarySchema.extend({+ key: z.string().min(1),+ forkedFromSkillId: z.string().uuid().nullable(),+ forkedFromCompanyId: z.string().uuid().nullable(),+ currentVersionId: z.string().uuid().nullable(),+ createdByCurrentActor: z.boolean(),+ diverged: z.boolean(),+ createdAt: z.coerce.date(),+ updatedAt: z.coerce.date(),+});+export const companySkillListQuerySchema = z.object({q: z.string().min(1).optional(),sort: companySkillListSortSchema.optional(),@@ -100,6 +120,7 @@ export const companySkillVersionSchema = z.object({export const companySkillDetailSchema = companySkillSchema.extend({attachedAgentCount: z.number().int().nonnegative(),usedByAgents: z.array(companySkillUsageAgentSchema).default([]),+ existingForks: z.array(companySkillForkSummarySchema).default([]),editable: z.boolean(),editableReason: z.string().nullable(),sourceLabel: z.string().nullable(),@@ -144,8 +165,29 @@ export const companySkillForkSchema = z.object({name: z.string().min(1).nullable().optional(),slug: z.string().min(1).nullable().optional(),sharingScope: companySkillSharingScopeSchema.optional(),+ reassignAgentIds: z.array(z.string().uuid()).optional(),}).default({});+export const companySkillForkReassignmentSchema = z.object({+ agentId: z.string().uuid(),+ previousSkillKey: z.string().min(1),+ nextSkillKey: z.string().min(1),+});++export const companySkillForkResultSchema = z.object({+ skill: companySkillSchema,+ original: companySkillOriginalSummarySchema,+ reassignments: z.array(companySkillForkReassignmentSchema),+});++export const companySkillForkPrecheckResultSchema = z.object({+ skillId: z.string().uuid(),+ original: companySkillOriginalSummarySchema,+ agentUsageCount: z.number().int().nonnegative(),+ usedByAgents: z.array(companySkillUsageAgentSchema),+ existingForks: z.array(companySkillForkSummarySchema),+});+export const companySkillUpdateSchema = z.object({description: z.string().nullable().optional(),iconUrl: z.string().nullable().optional(),diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex 1dc44e0592..1d3d3b4284 100644--- a/packages/shared/src/validators/index.ts+++ b/packages/shared/src/validators/index.ts@@ -119,6 +119,11 @@ export {companySkillCommentCreateSchema,companySkillCommentUpdateSchema,companySkillForkSchema,+ companySkillOriginalSummarySchema,+ companySkillForkSummarySchema,+ companySkillForkReassignmentSchema,+ companySkillForkResultSchema,+ companySkillForkPrecheckResultSchema,companySkillUpdateSchema,companySkillUpdateStatusSchema,companySkillAuditFindingSchema,diff --git a/server/src/__tests__/company-skills-routes.test.ts b/server/src/__tests__/company-skills-routes.test.tsindex ca8abc4d21..c964c4b15e 100644--- a/server/src/__tests__/company-skills-routes.test.ts+++ b/server/src/__tests__/company-skills-routes.test.ts@@ -21,6 +21,7 @@ const mockCompanySkillService = vi.hoisted(() => ({starSkill: vi.fn(),unstarSkill: vi.fn(),forkSkill: vi.fn(),+ forkPrecheck: vi.fn(),listComments: vi.fn(),createComment: vi.fn(),updateComment: vi.fn(),@@ -150,7 +151,7 @@ describe("company skill mutation permissions", () => {starred: false,starCount: 0,});- mockCompanySkillService.forkSkill.mockResolvedValue({+ const forkedSkill = {id: "skill-fork",companyId: "company-1",key: "company/company-1/review-fork",@@ -181,6 +182,32 @@ describe("company skill mutation permissions", () => {metadata: null,createdAt: new Date("2026-05-26T00:00:00.000Z"),updatedAt: new Date("2026-05-26T00:00:00.000Z"),+ };+ mockCompanySkillService.forkSkill.mockResolvedValue({+ skill: forkedSkill,+ original: {+ id: "skill-1",+ name: "Review",+ slug: "review",+ sourceType: "github",+ sourceLocator: "https://github.com/acme/review",+ sourceRef: "abc123",+ },+ reassignments: [],+ });+ mockCompanySkillService.forkPrecheck.mockResolvedValue({+ skillId: "skill-1",+ original: {+ id: "skill-1",+ name: "Review",+ slug: "review",+ sourceType: "github",+ sourceLocator: "https://github.com/acme/review",+ sourceRef: "abc123",+ },+ agentUsageCount: 0,+ usedByAgents: [],+ existingForks: [],});mockCompanySkillService.listComments.mockResolvedValue([]);mockCompanySkillService.createComment.mockResolvedValue({@@ -834,8 +861,27 @@ describe("company skill mutation permissions", () => {userId: "user-1",});- await request(app).post("/api/companies/company-1/skills/skill-1/fork").send({ slug: "review-fork" }).expect(201);- expect(mockCompanySkillService.forkSkill).toHaveBeenCalledWith("company-1", "skill-1", { slug: "review-fork" }, {+ const forkRes = await request(app)+ .post("/api/companies/company-1/skills/skill-1/fork")+ .send({ slug: "review-fork", reassignAgentIds: ["11111111-1111-4111-8111-111111111111"] })+ .expect(201);+ expect(forkRes.body).toMatchObject({+ skill: { id: "skill-fork", slug: "review-fork" },+ original: { id: "skill-1", slug: "review" },+ reassignments: [],+ });+ expect(mockCompanySkillService.forkSkill).toHaveBeenCalledWith(+ "company-1",+ "skill-1",+ { slug: "review-fork", reassignAgentIds: ["11111111-1111-4111-8111-111111111111"] },+ {+ type: "user",+ userId: "user-1",+ },+ );++ await request(app).get("/api/companies/company-1/skills/skill-1/fork-precheck").expect(200);+ expect(mockCompanySkillService.forkPrecheck).toHaveBeenCalledWith("company-1", "skill-1", {type: "user",userId: "user-1",});diff --git a/server/src/__tests__/company-skills-service.test.ts b/server/src/__tests__/company-skills-service.test.tsindex 81d9158950..e4a01860c0 100644--- a/server/src/__tests__/company-skills-service.test.ts+++ b/server/src/__tests__/company-skills-service.test.ts@@ -3,6 +3,7 @@ import os from "node:os";import path from "node:path";import { promises as fs } from "node:fs";import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";+import { eq } from "drizzle-orm";import { agents, companies, companySkills, createDb } from "@paperclipai/db";import {getEmbeddedPostgresTestSupport,@@ -428,12 +429,24 @@ describeEmbeddedPostgres("companySkillService.list", () => {authorUserId: "board",});- const dedicatedFork = await svc.forkSkill(+ const dedicatedForkResult = await svc.forkSkill(companyId,sourceSkillId,{ name: "Dedicated Fork", slug: "dedicated-fork", sharingScope: "private" },{ type: "user", userId: "board" },);+ const dedicatedFork = dedicatedForkResult.skill;+ expect(dedicatedForkResult).toMatchObject({+ original: {+ id: sourceSkillId,+ name: "Source Skill",+ slug: "source-skill",+ sourceType: "local_path",+ sourceLocator: sourceSkillDir,+ sourceRef: null,+ },+ reassignments: [],+ });expect(dedicatedFork).toMatchObject({name: "Source Skill",slug: "dedicated-fork",@@ -451,6 +464,167 @@ describeEmbeddedPostgres("companySkillService.list", () => {});});+ it("prechecks existing forks and reassigns selected agents when forking", async () => {+ const companyId = randomUUID();+ const sourceSkillId = randomUUID();+ const sourceSkillDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-reassign-source-"));+ cleanupDirs.add(sourceSkillDir);+ await fs.writeFile(path.join(sourceSkillDir, "SKILL.md"), "# Source Skill\n", "utf8");+ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,+ requireBoardApprovalForNewAgents: false,+ });+ await db.insert(companySkills).values({+ id: sourceSkillId,+ companyId,+ key: `company/${companyId}/source-skill`,+ slug: "source-skill",+ name: "Source Skill",+ description: null,+ markdown: "# Source Skill\n",+ sourceType: "local_path",+ sourceLocator: sourceSkillDir,+ trustLevel: "markdown_only",+ compatibility: "compatible",+ fileInventory: [{ path: "SKILL.md", kind: "skill" }],+ metadata: { sourceKind: "managed_local" },+ });+ const reassignAgentId = randomUUID();+ const keepAgentId = randomUUID();+ await db.insert(agents).values([+ {+ id: reassignAgentId,+ companyId,+ name: "Reassign Me",+ role: "engineer",+ adapterType: "codex_local",+ adapterConfig: {+ paperclipSkillSync: {+ desiredSkills: [`company/${companyId}/source-skill`],+ },+ },+ },+ {+ id: keepAgentId,+ companyId,+ name: "Keep Me",+ role: "engineer",+ adapterType: "codex_local",+ adapterConfig: {+ paperclipSkillSync: {+ desiredSkills: [`company/${companyId}/source-skill`],+ },+ },+ },+ ]);++ const before = await svc.forkPrecheck(companyId, sourceSkillId, { type: "user", userId: "board" });+ expect(before).toMatchObject({+ skillId: sourceSkillId,+ original: { id: sourceSkillId, slug: "source-skill" },+ agentUsageCount: 2,+ existingForks: [],+ });++ const forked = await svc.forkSkill(+ companyId,+ sourceSkillId,+ { slug: "source-skill-fork", reassignAgentIds: [reassignAgentId] },+ { type: "user", userId: "board" },+ );++ expect(forked).toMatchObject({+ skill: {+ slug: "source-skill-fork",+ key: `company/${companyId}/source-skill-fork`,+ forkedFromSkillId: sourceSkillId,+ },+ original: { id: sourceSkillId, slug: "source-skill" },+ reassignments: [{+ agentId: reassignAgentId,+ previousSkillKey: `company/${companyId}/source-skill`,+ nextSkillKey: `company/${companyId}/source-skill-fork`,+ }],+ });+ const afterAgents = await db.select().from(agents).where(eq(agents.companyId, companyId));+ const reassignConfig = afterAgents.find((agent) => agent.id === reassignAgentId)?.adapterConfig as Record<string, any>;+ const keepConfig = afterAgents.find((agent) => agent.id === keepAgentId)?.adapterConfig as Record<string, any>;+ expect(reassignConfig.paperclipSkillSync.desiredSkills).toEqual([`company/${companyId}/source-skill-fork`]);+ expect(keepConfig.paperclipSkillSync.desiredSkills).toEqual([`company/${companyId}/source-skill`]);++ const after = await svc.forkPrecheck(companyId, sourceSkillId, { type: "user", userId: "board" });+ expect(after?.existingForks).toEqual([+ expect.objectContaining({+ id: forked.skill.id,+ key: forked.skill.key,+ createdByCurrentActor: true,+ diverged: false,+ }),+ ]);+ });++ it("forks external source types and deduplicates fork slugs", async () => {+ const companyId = randomUUID();+ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,+ requireBoardApprovalForNewAgents: false,+ });+ const sourceTypes = ["github", "skills_sh", "url", "catalog"] as const;+ await db.insert(companySkills).values(sourceTypes.map((sourceType) => ({+ id: randomUUID(),+ companyId,+ key: `company/${companyId}/${sourceType}-skill`,+ slug: `${sourceType}-skill`,+ name: `${sourceType} Skill`,+ description: null,+ markdown: `# ${sourceType} Skill\n`,+ sourceType,+ sourceLocator: sourceType === "url"+ ? `https://example.com/${sourceType}.md`+ : sourceType === "catalog"+ ? null+ : `https://github.com/acme/${sourceType}-skill`,+ sourceRef: sourceType === "github" || sourceType === "skills_sh" ? "main" : null,+ trustLevel: "markdown_only",+ compatibility: "compatible",+ fileInventory: [{ path: "SKILL.md", kind: "skill" }],+ metadata: sourceType === "github" || sourceType === "skills_sh"+ ? { sourceKind: sourceType, owner: "acme", repo: `${sourceType}-skill`, ref: "main", repoSkillDir: "." }+ : { sourceKind: sourceType },+ })));++ const remoteReads: string[] = [];+ vi.stubGlobal("fetch", async (url: string | URL) => {+ remoteReads.push(String(url));+ return new Response("# Remote Skill\n", { status: 200 });+ });+ try {+ for (const sourceType of sourceTypes) {+ const source = await svc.getByKey(companyId, `company/${companyId}/${sourceType}-skill`);+ expect(source).not.toBeNull();+ const first = await svc.forkSkill(companyId, source!.id, { slug: `${sourceType}-skill-fork` }, { type: "user", userId: "board" });+ const second = await svc.forkSkill(companyId, source!.id, { slug: `${sourceType}-skill-fork` }, { type: "user", userId: "board" });+ const normalizedForkSlug = `${sourceType.replace("_", "-")}-skill-fork`;+ expect(first.skill).toMatchObject({+ slug: normalizedForkSlug,+ sourceType: "local_path",+ forkedFromSkillId: source!.id,+ });+ expect(second.skill.slug).toBe(`${normalizedForkSlug}-2`);+ }+ } finally {+ vi.unstubAllGlobals();+ }+ expect(remoteReads).toEqual(expect.arrayContaining([+ "https://raw.githubusercontent.com/acme/github-skill/main/SKILL.md",+ "https://raw.githubusercontent.com/acme/skills_sh-skill/main/SKILL.md",+ ]));+ });+it("validates version-aware desired skill selections", async () => {const companyId = randomUUID();const skillId = randomUUID();diff --git a/server/src/__tests__/heartbeat-workspace-branch-containment.test.ts b/server/src/__tests__/heartbeat-workspace-branch-containment.test.tsindex cc32d23890..be561dbbba 100644--- a/server/src/__tests__/heartbeat-workspace-branch-containment.test.ts+++ b/server/src/__tests__/heartbeat-workspace-branch-containment.test.ts@@ -172,13 +172,35 @@ async function waitForRunToFinish(heartbeat: Heartbeat, runId: string, timeoutMsasync function waitForHeartbeatIdle(db: Db, timeoutMs = 5_000) {const deadline = Date.now() + timeoutMs;+ let idleSince: number | null = null;while (Date.now() < deadline) {const runs = await db.select({ status: heartbeatRuns.status }).from(heartbeatRuns);- if (!runs.some((run) => run.status === "queued" || run.status === "running")) return;+ if (!runs.some((run) => run.status === "queued" || run.status === "running")) {+ idleSince ??= Date.now();+ if (Date.now() - idleSince >= 250) return;+ } else {+ idleSince = null;+ }await new Promise((resolve) => setTimeout(resolve, 50));}}+async function deleteHeartbeatRunsForCleanup(db: Db) {+ let lastError: unknown = null;+ for (let attempt = 0; attempt < 5; attempt += 1) {+ await db.delete(heartbeatRunEvents);+ await db.delete(activityLog);+ try {+ await db.delete(heartbeatRuns);+ return;+ } catch (error) {+ lastError = error;+ await new Promise((resolve) => setTimeout(resolve, 50));+ }+ }+ throw lastError;+}+async function waitForContainmentSideEffects(input: {db: Db;companyId: string;@@ -873,9 +895,7 @@ describeEmbeddedPostgres("heartbeat workspace branch containment", () => {await db.delete(heartbeatRunEvents);// Heartbeat failure/finalization paths can emit run-linked events and// activity after the first cleanup pass observes all runs as non-active.- await db.delete(heartbeatRunEvents);- await db.delete(activityLog);- await db.delete(heartbeatRuns);+ await deleteHeartbeatRunsForCleanup(db);await db.delete(issueComments);await db.delete(issues);await db.delete(projectWorkspaces);diff --git a/server/src/routes/company-skills.ts b/server/src/routes/company-skills.tsindex a58e7a6c24..78111febfc 100644--- a/server/src/routes/company-skills.ts+++ b/server/src/routes/company-skills.ts@@ -179,6 +179,18 @@ export function companySkillRoutes(db: Db) {res.json(result);});+ router.get("/companies/:companyId/skills/:skillId/fork-precheck", async (req, res) => {+ const companyId = req.params.companyId as string;+ const skillId = req.params.skillId as string;+ assertCompanyAccess(req, companyId);+ const result = await svc.forkPrecheck(companyId, skillId, skillActor(req));+ if (!result) {+ res.status(404).json({ error: "Skill not found" });+ return;+ }+ res.json(result);+ });+router.get("/companies/:companyId/skills/:skillId/versions", async (req, res) => {const companyId = req.params.companyId as string;const skillId = req.params.skillId as string;@@ -284,11 +296,12 @@ export function companySkillRoutes(db: Db) {runId: actor.runId,action: "company.skill_forked",entityType: "company_skill",- entityId: result.id,+ entityId: result.skill.id,details: {sourceSkillId: skillId,- slug: result.slug,- name: result.name,+ slug: result.skill.slug,+ name: result.skill.name,+ reassignedAgentIds: result.reassignments.map((entry: { agentId: string }) => entry.agentId),},});res.status(201).json(result);diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.tsindex 69511eae35..c6860154d8 100644--- a/server/src/routes/openapi.ts+++ b/server/src/routes/openapi.ts@@ -4862,6 +4862,7 @@ for (const route of [["get", "/api/companies/{companyId}/skills/{skillId}/versions/{versionId}", "Get a skill version"],["post", "/api/companies/{companyId}/skills/{skillId}/star", "Star a company skill"],["delete", "/api/companies/{companyId}/skills/{skillId}/star", "Unstar a company skill"],+ ["get", "/api/companies/{companyId}/skills/{skillId}/fork-precheck", "Preview company skill fork impact"],["post", "/api/companies/{companyId}/skills/{skillId}/fork", "Fork a company skill"],["get", "/api/companies/{companyId}/skills/{skillId}/comments", "List skill comments"],["post", "/api/companies/{companyId}/skills/{skillId}/comments", "Create a skill comment"],diff --git a/server/src/services/company-skills.ts b/server/src/services/company-skills.tsindex e0cfc930b6..6d23e80861 100644--- a/server/src/services/company-skills.ts+++ b/server/src/services/company-skills.ts@@ -4,8 +4,8 @@ import path from "node:path";import { fileURLToPath } from "node:url";import { and, asc, desc, eq, isNull, sql } from "drizzle-orm";import type { Db } from "@paperclipai/db";-import { companies, companySkillComments, companySkillStars, companySkillVersions, companySkills } from "@paperclipai/db";-import { readPaperclipSkillSyncPreference } from "@paperclipai/adapter-utils/server-utils";+import { agents as agentsTable, companies, companySkillComments, companySkillStars, companySkillVersions, companySkills } from "@paperclipai/db";+import { readPaperclipSkillSyncPreference, writePaperclipSkillSyncPreference } from "@paperclipai/adapter-utils/server-utils";import type { PaperclipDesiredSkillEntry, PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils";import type {AgentDesiredSkillEntry,@@ -23,12 +23,17 @@ import type {CompanySkillDetail,CompanySkillFileDetail,CompanySkillFileInventoryEntry,+ CompanySkillForkPrecheckResult,CompanySkillForkRequest,+ CompanySkillForkResult,+ CompanySkillForkReassignment,+ CompanySkillForkSummary,CompanySkillImportResult,CompanySkillInstallCatalogRequest,CompanySkillInstallCatalogResult,CompanySkillListQuery,CompanySkillListItem,+ CompanySkillOriginalSummary,CompanySkillProjectScanConflict,CompanySkillProjectScanRequest,CompanySkillProjectScanResult,@@ -247,6 +252,8 @@ type SkillSourceMeta = {originVersion?: string;originSnapshotLocator?: string;installedHash?: string;+ forkedByAgentId?: string | null;+ forkedByUserId?: string | null;userModifiedAt?: string | null;updateHoldReason?: CompanySkillUpdateHoldReason | null;auditVerdict?: CompanySkillAuditVerdict;@@ -284,6 +291,11 @@ type SkillActor = {userId?: string | null;};+type PlannedSkillReassignment = {+ agentId: string;+ reassignment: CompanySkillForkReassignment;+};+type RuntimeSkillSourceResolution =| { status: "available"; source: string }| { status: "missing"; source: string; detail: string };@@ -2063,18 +2075,61 @@ function enrichSkill(usedByAgents: CompanySkillUsageAgent[] = [],currentVersion: CompanySkillVersion | null = null,starredByCurrentActor = false,+ existingForks: CompanySkillForkSummary[] = [],) {const source = deriveSkillSourceInfo(skill);return {...skill,attachedAgentCount,usedByAgents,+ existingForks,currentVersion,starredByCurrentActor,...source,};}+function summarizeOriginalSkill(skill: CompanySkill): CompanySkillOriginalSummary {+ return {+ id: skill.id,+ name: skill.name,+ slug: skill.slug,+ sourceType: skill.sourceType,+ sourceLocator: skill.sourceLocator,+ sourceRef: skill.sourceRef,+ };+}++function forkCreatedByActor(skill: CompanySkill, actor?: SkillActor | null) {+ const metadata = getSkillMeta(skill);+ if (actor?.type === "agent" && actor.agentId) {+ return asString(metadata.forkedByAgentId) === actor.agentId;+ }+ if (actor?.type === "user" && actor.userId) {+ return asString(metadata.forkedByUserId) === actor.userId;+ }+ return false;+}++function summarizeForkSkill(+ skill: CompanySkill,+ actor: SkillActor | null | undefined,+ versionCount: number,+): CompanySkillForkSummary {+ const metadata = getSkillMeta(skill);+ return {+ ...summarizeOriginalSkill(skill),+ key: skill.key,+ forkedFromSkillId: skill.forkedFromSkillId,+ forkedFromCompanyId: skill.forkedFromCompanyId,+ currentVersionId: skill.currentVersionId,+ createdByCurrentActor: forkCreatedByActor(skill, actor),+ diverged: versionCount > 1 || Boolean(asString(metadata.userModifiedAt)),+ createdAt: skill.createdAt,+ updatedAt: skill.updatedAt,+ };+}+function toCompanySkillListItem(skill: CompanySkillListRow, attachedAgentCount: number): CompanySkillListItem {const source = deriveSkillSourceInfo(skill);const metadata = getSkillMeta(skill);@@ -2495,20 +2550,66 @@ export function companySkillService(db: Db) {}));}+ async function versionCount(companyId: string, skillId: string) {+ const [{ value }] = await db+ .select({ value: sql<number>`count(*)::int` })+ .from(companySkillVersions)+ .where(and(eq(companySkillVersions.companyId, companyId), eq(companySkillVersions.companySkillId, skillId)));+ return Number(value ?? 0);+ }++ async function existingForkSummaries(+ companyId: string,+ sourceSkillId: string,+ actor?: SkillActor | null,+ ): Promise<CompanySkillForkSummary[]> {+ const rows = await db+ .select(selectCompanySkillColumns())+ .from(companySkills)+ .where(and(eq(companySkills.companyId, companyId), eq(companySkills.forkedFromSkillId, sourceSkillId)))+ .orderBy(desc(companySkills.updatedAt), asc(companySkills.name));+ const summaries: CompanySkillForkSummary[] = [];+ for (const row of rows) {+ const skill = toCompanySkill(row);+ summaries.push(summarizeForkSkill(skill, actor, await versionCount(companyId, skill.id)));+ }+ return summaries;+ }+async function detail(companyId: string, id: string, actor?: SkillActor | null): Promise<CompanySkillDetail | null> {await ensureSkillInventoryCurrent(companyId);const skill = await getById(companyId, id);if (!skill) return null;const usedByAgents = await usage(companyId, skill.key);+ const existingForks = await existingForkSummaries(companyId, skill.id, actor);return enrichSkill(skill,usedByAgents.length,usedByAgents,await getCurrentVersion(skill),await isStarredByActor(companyId, id, actor),+ existingForks,);}+ async function forkPrecheck(+ companyId: string,+ skillId: string,+ actor?: SkillActor | null,+ ): Promise<CompanySkillForkPrecheckResult | null> {+ await ensureSkillInventoryCurrent(companyId);+ const skill = await getById(companyId, skillId);+ if (!skill) return null;+ const usedByAgents = await usage(companyId, skill.key);+ return {+ skillId: skill.id,+ original: summarizeOriginalSkill(skill),+ agentUsageCount: usedByAgents.length,+ usedByAgents,+ existingForks: await existingForkSummaries(companyId, skill.id, actor),+ };+ }+async function collectVersionFileInventory(companyId: string,skill: CompanySkill,@@ -2759,12 +2860,136 @@ export function companySkillService(db: Db) {return toCompanySkillComment(row);}+ async function planSkillReassignments(+ companyId: string,+ source: CompanySkill,+ forkKey: string,+ reassignAgentIds: string[] | undefined,+ ): Promise<PlannedSkillReassignment[]> {+ const requestedAgentIds = Array.from(new Set(reassignAgentIds ?? []));+ if (requestedAgentIds.length === 0) return [];++ const skills = await listReferenceTargets(companyId);+ const agentRows = await agents.list(companyId, { includeTerminated: true });+ const byId = new Map(agentRows.map((agent) => [agent.id, agent]));+ const missingAgentIds = requestedAgentIds.filter((agentId) => !byId.has(agentId));+ if (missingAgentIds.length > 0) {+ throw notFound(`Agent not found for skill reassignment: ${missingAgentIds.join(", ")}`);+ }++ return requestedAgentIds.map((agentId) => {+ const agent = byId.get(agentId)!;+ if (agent.companyId !== companyId) {+ throw unprocessable("Cannot reassign a skill for an agent in another company.", { agentId });+ }+ const adapterConfig = agent.adapterConfig as Record<string, unknown>;+ const desiredEntries = resolveDesiredSkillEntries(skills, adapterConfig);+ const hasSource = desiredEntries.some((entry) => entry.key === source.key);+ if (!hasSource) {+ throw unprocessable(`Agent "${agent.name}" does not currently use skill "${source.name}".`, {+ agentId,+ skillId: source.id,+ skillKey: source.key,+ });+ }+ return {+ agentId,+ reassignment: {+ agentId,+ previousSkillKey: source.key,+ nextSkillKey: forkKey,+ },+ };+ });+ }++ async function applySkillReassignments(+ companyId: string,+ source: CompanySkill,+ forkKey: string,+ planned: PlannedSkillReassignment[],+ ): Promise<CompanySkillForkReassignment[]> {+ if (planned.length === 0) return [];+ const skills = await listReferenceTargets(companyId);+ await db.transaction(async (tx) => {+ for (const item of planned) {+ const row = await tx+ .select({+ id: agentsTable.id,+ name: agentsTable.name,+ adapterConfig: agentsTable.adapterConfig,+ })+ .from(agentsTable)+ .where(and(eq(agentsTable.companyId, companyId), eq(agentsTable.id, item.agentId)))+ .for("update")+ .then((rows) => rows[0] ?? null);+ if (!row) throw notFound(`Agent not found for skill reassignment: ${item.agentId}`);+ const adapterConfig = row.adapterConfig as Record<string, unknown>;+ const desiredEntries = resolveDesiredSkillEntries(skills, adapterConfig);+ const hasSource = desiredEntries.some((entry) => entry.key === source.key);+ if (!hasSource) {+ throw unprocessable(`Agent "${row.name}" does not currently use skill "${source.name}".`, {+ agentId: item.agentId,+ skillId: source.id,+ skillKey: source.key,+ });+ }+ const nextEntries = desiredEntries.map((entry) =>+ entry.key === source.key+ ? { key: forkKey, versionId: null }+ : entry+ );+ const updated = await tx+ .update(agentsTable)+ .set({+ adapterConfig: writePaperclipSkillSyncPreference(adapterConfig, nextEntries),+ updatedAt: new Date(),+ })+ .where(and(eq(agentsTable.companyId, companyId), eq(agentsTable.id, item.agentId)))+ .returning({ id: agentsTable.id })+ .then((rows) => rows[0] ?? null);+ if (!updated) throw notFound(`Agent not found for skill reassignment: ${item.agentId}`);+ }+ });+ return planned.map((item) => item.reassignment);+ }++ async function cleanupFailedFork(companyId: string, sourceSkillId: string, forkSkillId: string, forkDir: string) {+ await db.transaction(async (tx) => {+ await tx+ .update(companySkills)+ .set({ currentVersionId: null, updatedAt: new Date() })+ .where(and(eq(companySkills.id, forkSkillId), eq(companySkills.companyId, companyId)));+ await tx+ .delete(companySkillComments)+ .where(and(eq(companySkillComments.companyId, companyId), eq(companySkillComments.companySkillId, forkSkillId)));+ await tx+ .delete(companySkillStars)+ .where(and(eq(companySkillStars.companyId, companyId), eq(companySkillStars.companySkillId, forkSkillId)));+ await tx+ .delete(companySkillVersions)+ .where(and(eq(companySkillVersions.companyId, companyId), eq(companySkillVersions.companySkillId, forkSkillId)));+ await tx+ .delete(companySkills)+ .where(and(eq(companySkills.id, forkSkillId), eq(companySkills.companyId, companyId)));+ await tx+ .update(companySkills)+ .set({+ forkCount: sql`greatest(${companySkills.forkCount} - 1, 0)`,+ installCount: sql`greatest(${companySkills.installCount} - 1, 0)`,+ updatedAt: new Date(),+ })+ .where(and(eq(companySkills.id, sourceSkillId), eq(companySkills.companyId, companyId)));+ });+ await fs.rm(forkDir, { recursive: true, force: true });+ }+async function forkSkill(companyId: string,skillId: string,input: CompanySkillForkRequest = {},actor: SkillActor | null = null,- ): Promise<CompanySkill> {+ ): Promise<CompanySkillForkResult> {await ensureSkillInventoryCurrent(companyId);const source = await getById(companyId, skillId);if (!source) throw notFound("Skill not found");@@ -2772,6 +2997,8 @@ export function companySkillService(db: Db) {const usedSlugs = new Set(existing.map((skill) => normalizeSkillSlug(skill.slug) ?? skill.slug));const forkSlug = uniqueSkillSlug(normalizeSkillSlug(input.slug ?? `${source.slug}-fork`) ?? `${source.slug}-fork`, usedSlugs);const forkName = input.name?.trim() || `${source.name} Fork`;+ const forkKey = `company/${companyId}/${forkSlug}`;+ const plannedReassignments = await planSkillReassignments(companyId, source, forkKey, input.reassignAgentIds);const managedRoot = resolveManagedSkillsRoot(companyId);const forkDir = path.resolve(managedRoot, forkSlug);await fs.rm(forkDir, { recursive: true, force: true });@@ -2798,7 +3025,7 @@ export function companySkillService(db: Db) {forkedByUserId: actor?.type === "user" ? actor.userId ?? null : null,};const imported = await upsertImportedSkills(companyId, [{- key: `company/${companyId}/${forkSlug}`,+ key: forkKey,slug: forkSlug,name: asString(parsed.frontmatter.name) ?? forkName,description: asString(parsed.frontmatter.description) ?? source.description,@@ -2836,10 +3063,22 @@ export function companySkillService(db: Db) {}).where(and(eq(companySkills.id, source.id), eq(companySkills.companyId, companyId)));await createVersion(companyId, forked.id, { label: "Initial version" }, actor);- return getById(companyId, forked.id).then((skill) => {+ const persistedFork = await getById(companyId, forked.id).then((skill) => {if (!skill) throw notFound("Forked skill not found");return skill;});+ let reassignments: CompanySkillForkReassignment[];+ try {+ reassignments = await applySkillReassignments(companyId, source, forkKey, plannedReassignments);+ } catch (error) {+ await cleanupFailedFork(companyId, source.id, forked.id, forkDir);+ throw error;+ }+ return {+ skill: persistedFork,+ original: summarizeOriginalSkill(source),+ reassignments,+ };}async function updateStatus(companyId: string, skillId: string): Promise<CompanySkillUpdateStatus | null> {@@ -4463,6 +4702,7 @@ export function companySkillService(db: Db) {},categoryCounts,detail,+ forkPrecheck,listVersions,getVersion,createVersion,diff --git a/ui/src/pages/CompanySkills.test.tsx b/ui/src/pages/CompanySkills.test.tsxindex 988d088aee..5770f7fa4f 100644--- a/ui/src/pages/CompanySkills.test.tsx+++ b/ui/src/pages/CompanySkills.test.tsx@@ -158,6 +158,7 @@ function makeDetail(currentVersion: CompanySkillVersion, overrides: Partial<CompupdatedAt: new Date("2026-01-02T00:00:00Z"),attachedAgentCount: 0,usedByAgents: [],+ existingForks: [],editable: true,editableReason: null,sourceLabel: "Local",diff --git a/ui/storybook/stories/skills-store-detail.stories.tsx b/ui/storybook/stories/skills-store-detail.stories.tsxindex b0b95ecbfc..56a160cc79 100644--- a/ui/storybook/stories/skills-store-detail.stories.tsx+++ b/ui/storybook/stories/skills-store-detail.stories.tsx@@ -48,6 +48,7 @@ const MOCK_DETAIL: CompanySkillDetail = {createdAt: NOW,updatedAt: NOW,attachedAgentCount: 4,+ existingForks: [],usedByAgents: [{ id: "a-1", name: "Astra", urlKey: "astra", adapterType: "process", desired: true, actualState: null, versionId: null },{ id: "a-2", name: "Scout", urlKey: "scout", adapterType: "http", desired: true, actualState: null, versionId: null },