Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(skills): track draft changes and fetch file contents by hash (#18062)

tobi_kl8ff680b1bde7
diff --git a/fern/apis/server/definition/unstable/skills.yml b/fern/apis/server/definition/unstable/skills.yml
index 87a8ee36e4..7fadb32e09 100644
--- a/fern/apis/server/definition/unstable/skills.yml
+++ b/fern/apis/server/definition/unstable/skills.yml
@@ -42,7 +42,7 @@ service:
type: SkillVersion
get:
- docs: Resolve a skill's metadata and file manifest by version or label. Defaults to the production label. Use each file's id with getFileContent to read its text content.
+ docs: Resolve a skill's metadata and file manifest by version or label. Defaults to the production label. Use each file's sha256Hash with getFileContents, individually or in batches across manifests.
method: GET
path: /skills/{skillName}
path-parameters:
@@ -63,13 +63,21 @@ service:
request: UpdateSkillRequest
response: SkillVersion
- getFileContent:
- docs: Read one text file from a persisted skill version using its file id, not its blob id. Returns JSON containing the text content with Cache-Control no-store.
+ getFileContents:
+ docs: |
+ Read a batch of text contents by canonical base64-encoded SHA-256 hashes.
method: GET
- path: /skills/files/{fileId}/content
- path-parameters:
- fileId: string
- response: SkillFileContentResponse
+ path: /skills/files/content
+ request:
+ name: GetSkillFileContentsRequest
+ query-parameters:
+ sha256Hashes:
+ type: string
+ docs: >
+ Comma-separated list of one to 50 canonical base64-encoded SHA-256
+ hashes from skill file manifests. URL-encode the value, including
+ +, /, and = characters.
+ response: SkillFileContentsResponse
setLabels:
docs: Replace the labels on a skill version and atomically move them from other versions.
@@ -148,8 +156,13 @@ types:
contentType: string
contentLength: long
- SkillFileContentResponse:
+ SkillFileContentsResponse:
properties:
+ data: list<SkillFileContent>
+
+ SkillFileContent:
+ properties:
+ sha256Hash: string
content: string
SkillVersion:
diff --git a/packages/shared/src/features/skills/types.ts b/packages/shared/src/features/skills/types.ts
index 6b8f9722ad..710c37b4d1 100644
--- a/packages/shared/src/features/skills/types.ts
+++ b/packages/shared/src/features/skills/types.ts
@@ -248,10 +248,6 @@ export const SkillFileSchema = z.object({
contentLength: z.number().int(),
});
-export const SkillFileContentResponseSchema = z.object({
- content: z.string(),
-});
-
export const SkillVersionSchema = z.object({
id: z.string(),
createdAt: z.coerce.date(),
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index 29a6bcef8e..cebaa95437 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -8873,8 +8873,8 @@ paths:
get:
description: >-
Resolve a skill's metadata and file manifest by version or label.
- Defaults to the production label. Use each file's id with getFileContent
- to read its text content.
+ Defaults to the production label. Use each file's sha256Hash with
+ getFileContents, individually or in batches across manifests.
operationId: unstable_skills_get
tags:
- UnstableSkills
@@ -8982,18 +8982,20 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateSkillRequest'
- /api/public/unstable/skills/files/{fileId}/content:
+ /api/public/unstable/skills/files/content:
get:
description: >-
- Read one text file from a persisted skill version using its file id, not
- its blob id. Returns JSON containing the text content with Cache-Control
- no-store.
- operationId: unstable_skills_getFileContent
+ Read a batch of text contents by canonical base64-encoded SHA-256 hashes.
+ operationId: unstable_skills_getFileContents
tags:
- UnstableSkills
parameters:
- - name: fileId
- in: path
+ - name: sha256Hashes
+ in: query
+ description: >-
+ Comma-separated list of one to 50 canonical base64-encoded SHA-256
+ hashes from skill file manifests. URL-encode the value, including +,
+ /, and = characters.
required: true
schema:
type: string
@@ -9003,7 +9005,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableSkillFileContentResponse'
+ $ref: '#/components/schemas/unstableSkillFileContentsResponse'
'400':
description: ''
content:
@@ -17893,13 +17895,26 @@ components:
- sha256Hash
- contentType
- contentLength
- unstableSkillFileContentResponse:
- title: unstableSkillFileContentResponse
+ unstableSkillFileContentsResponse:
+ title: unstableSkillFileContentsResponse
type: object
properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/unstableSkillFileContent'
+ required:
+ - data
+ unstableSkillFileContent:
+ title: unstableSkillFileContent
+ type: object
+ properties:
+ sha256Hash:
+ type: string
content:
type: string
required:
+ - sha256Hash
- content
unstableSkillVersion:
title: unstableSkillVersion
diff --git a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
index 68d643bb04..06722caee9 100644
--- a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
+++ b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
@@ -506,13 +506,13 @@ exports[`public-api auth parity > legacy matches the captured baseline except do
"GET unstable/skills/[skillName]/index | org/bearer": 401,
"GET unstable/skills/[skillName]/index | project/basic": 404,
"GET unstable/skills/[skillName]/index | project/bearer": 403,
- "GET unstable/skills/files/[fileId]/content | admin/admin": 401,
- "GET unstable/skills/files/[fileId]/content | agent/basic": 401,
- "GET unstable/skills/files/[fileId]/content | agent/bearer": 401,
- "GET unstable/skills/files/[fileId]/content | org/basic": 403,
- "GET unstable/skills/files/[fileId]/content | org/bearer": 401,
- "GET unstable/skills/files/[fileId]/content | project/basic": 404,
- "GET unstable/skills/files/[fileId]/content | project/bearer": 403,
+ "GET unstable/skills/files/content | admin/admin": 401,
+ "GET unstable/skills/files/content | agent/basic": 401,
+ "GET unstable/skills/files/content | agent/bearer": 401,
+ "GET unstable/skills/files/content | org/basic": 403,
+ "GET unstable/skills/files/content | org/bearer": 401,
+ "GET unstable/skills/files/content | project/basic": 404,
+ "GET unstable/skills/files/content | project/bearer": 403,
"GET unstable/skills/index | admin/admin": 401,
"GET unstable/skills/index | agent/basic": 401,
"GET unstable/skills/index | agent/bearer": 401,
diff --git a/web/src/__tests__/server/public-api-auth-parity.servertest.ts b/web/src/__tests__/server/public-api-auth-parity.servertest.ts
index f9fd6b2324..2c6fb4b798 100644
--- a/web/src/__tests__/server/public-api-auth-parity.servertest.ts
+++ b/web/src/__tests__/server/public-api-auth-parity.servertest.ts
@@ -124,7 +124,7 @@ const projectRoutes: Route[] = [
route: "unstable/skills/[skillName]/versions/[skillVersion]",
methods: ["PATCH", "DELETE"],
},
- { route: "unstable/skills/files/[fileId]/content", methods: ["GET"] },
+ { route: "unstable/skills/files/content", methods: ["GET"] },
];
// Org and misc routes call shadowAuth directly from the handler body.
@@ -190,6 +190,9 @@ function queryForRoute(route: string): Record<string, string> {
for (const match of route.matchAll(/\[([^\]]+)\]/g)) {
query[match[1]!] = nonexistentId;
}
+ if (route === "unstable/skills/files/content") {
+ query.sha256Hashes = Buffer.alloc(32).toString("base64");
+ }
return query;
}
diff --git a/web/src/__tests__/server/unit/skill-file-contents-get.servertest.ts b/web/src/__tests__/server/unit/skill-file-contents-get.servertest.ts
new file mode 100644
index 0000000000..2b2904bf5d
--- /dev/null
+++ b/web/src/__tests__/server/unit/skill-file-contents-get.servertest.ts
@@ -0,0 +1,119 @@
+import { createMocks } from "node-mocks-http";
+import type { NextApiRequest, NextApiResponse } from "next";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { getFileContents, shadowAuth } = vi.hoisted(() => ({
+ getFileContents: vi.fn(),
+ shadowAuth: vi.fn(),
+}));
+
+vi.mock("@/src/features/skills/server", () => ({
+ SkillService: class {
+ getFileContents = getFileContents;
+ },
+}));
+
+vi.mock("@/src/features/public-api/server/shadowAuth", () => ({ shadowAuth }));
+
+vi.mock("@/src/features/public-api/server/RateLimitService", () => ({
+ RateLimitService: {
+ getInstance: () => ({
+ rateLimitRequest: async () => ({ isRateLimited: () => false }),
+ }),
+ },
+}));
+
+vi.mock("@/src/features/ai-gateway/server", () => ({
+ verifyGatewayIngestionAuthorization: vi.fn(),
+}));
+
+vi.mock("@/src/features/public-api/server", async () => {
+ const { createAuthedProjectAPIRoute } =
+ await import("@/src/features/public-api/server/createAuthedProjectAPIRoute");
+ const { withMiddlewares } =
+ await import("@/src/features/public-api/server/withMiddlewares");
+ return { createAuthedProjectAPIRoute, withMiddlewares };
+});
+
+import handler from "@/src/pages/api/public/unstable/skills/files/content";
+
+const hashes = [
+ Buffer.alloc(32, 251).toString("base64"),
+ Buffer.alloc(32, 255).toString("base64"),
+];
+
+async function request(sha256Hashes?: string, method: "GET" | "POST" = "GET") {
+ const params = new URLSearchParams();
+ if (sha256Hashes !== undefined) params.set("sha256Hashes", sha256Hashes);
+ const url = `/api/public/unstable/skills/files/content?${params}`;
+ const { req, res } = createMocks<NextApiRequest, NextApiResponse>({
+ method,
+ url,
+ headers: { authorization: "Basic test" },
+ query: Object.fromEntries(new URL(url, "http://localhost").searchParams),
+ ...(method === "POST" ? { body: { sha256Hashes: hashes } } : {}),
+ });
+ await handler(req, res);
+ return res;
+}
+
+describe("GET /api/public/unstable/skills/files/content", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ shadowAuth.mockResolvedValue({
+ success: true,
+ scope: {
+ projectId: "project-1",
+ orgId: "org-1",
+ accessLevel: "project",
+ },
+ });
+ getFileContents.mockResolvedValue({ data: [] });
+ });
+
+ it("decodes comma-separated base64 hashes and retrieves content with read authorization", async () => {
+ const data = hashes.map((sha256Hash) => ({ sha256Hash, content: "text" }));
+ getFileContents.mockResolvedValue({ data });
+
+ const res = await request(hashes.join(","));
+
+ expect(res.statusCode).toBe(200);
+ expect(res._getJSONData()).toEqual({ data });
+ expect(res.getHeader("cache-control")).toBe("no-store");
+ expect(getFileContents).toHaveBeenCalledWith({
+ projectId: "project-1",
+ sha256Hashes: hashes,
+ });
+ expect(shadowAuth).toHaveBeenCalledWith(
+ expect.objectContaining({ action: "skills:read" }),
+ );
+ });
+
+ it("accepts 50 hashes and rejects 51 before invoking the service", async () => {
+ const batch = Array.from({ length: 51 }, (_, index) =>
+ Buffer.alloc(32, index).toString("base64"),
+ );
+ expect((await request(batch.slice(0, 50).join(","))).statusCode).toBe(200);
+ expect(getFileContents).toHaveBeenCalledWith({
+ projectId: "project-1",
+ sha256Hashes: batch.slice(0, 50),
+ });
+
+ getFileContents.mockClear();
+ expect((await request(batch.join(","))).statusCode).toBe(400);
+ expect(getFileContents).not.toHaveBeenCalled();
+ });
+
+ it.each([undefined, "", "not-a-sha256-hash", `${hashes[0]},`])(
+ "rejects an invalid hash query: %s",
+ async (query) => {
+ expect((await request(query)).statusCode).toBe(400);
+ expect(getFileContents).not.toHaveBeenCalled();
+ },
+ );
+
+ it("does not accept POST", async () => {
+ expect((await request(undefined, "POST")).statusCode).toBe(405);
+ expect(getFileContents).not.toHaveBeenCalled();
+ });
+});
diff --git a/web/src/__tests__/server/unit/skill-router.servertest.ts b/web/src/__tests__/server/unit/skill-router.servertest.ts
index 54f5c26c66..9398ff8e2e 100644
--- a/web/src/__tests__/server/unit/skill-router.servertest.ts
+++ b/web/src/__tests__/server/unit/skill-router.servertest.ts
@@ -6,7 +6,7 @@ import { createInnerTRPCContext } from "@/src/server/api/trpc";
const mocks = vi.hoisted(() => ({
get: vi.fn(),
- getFileContent: vi.fn(),
+ getFileContents: vi.fn(),
createVersion: vi.fn(),
setLabels: vi.fn(),
setTags: vi.fn(),
@@ -25,7 +25,7 @@ vi.mock("@/src/features/posthog-analytics/server/backendActivity", () => ({
vi.mock("@/src/features/skills/server/index", () => ({
SkillService: class {
get = mocks.get;
- getFileContent = mocks.getFileContent;
+ getFileContents = mocks.getFileContents;
createVersion = mocks.createVersion;
setLabels = mocks.setLabels;
setTags = mocks.setTags;
diff --git a/web/src/__tests__/server/unit/skill-service.servertest.ts b/web/src/__tests__/server/unit/skill-service.servertest.ts
index 8985b500cf..c0f9feb9aa 100644
--- a/web/src/__tests__/server/unit/skill-service.servertest.ts
+++ b/web/src/__tests__/server/unit/skill-service.servertest.ts
@@ -104,7 +104,7 @@ describe("SkillService versions", () => {
.mockResolvedValue({ id: "membership", role: "MEMBER" }),
},
projectMembership: { findFirst: vi.fn().mockResolvedValue(null) },
- skillFile: { findFirst: vi.fn().mockResolvedValue(skill.files[0]) },
+ skillBlob: { findMany: vi.fn().mockResolvedValue(blobs) },
$transaction: transaction,
skill: {
findFirst: vi.fn().mockResolvedValue(skill),
@@ -522,27 +522,33 @@ describe("SkillService versions", () => {
expect(test.transaction).not.toHaveBeenCalled();
});
- it("returns persisted text only after a project-scoped file lookup", async () => {
+ it("loads a resource through the batch lookup using its manifest hash", async () => {
const test = setup();
+ const getFileContents = vi
+ .spyOn(test.service, "getFileContents")
+ .mockResolvedValue({
+ data: [
+ {
+ sha256Hash: test.blobs[1]!.sha256Hash,
+ content: test.blobs[1]!.content,
+ },
+ ],
+ });
+ const input = {
+ projectId: "project",
+ name: "test-skill",
+ selector: { version: 1 },
+ };
await expect(
- test.service.getFileContent({ projectId: "project", fileId: "file-0" }),
- ).resolves.toEqual({ content: test.blobs[0]!.content });
- expect(test.db.skillFile.findFirst).toHaveBeenCalledWith(
- expect.objectContaining({
- where: { projectId: "project", id: "file-0" },
- }),
- );
- test.db.skillFile.findFirst.mockResolvedValue(null);
+ test.service.loadResource({ ...input, path: "reference.txt" }),
+ ).resolves.toBe(test.blobs[1]!.content);
+ expect(getFileContents).toHaveBeenCalledExactlyOnceWith({
+ projectId: "project",
+ sha256Hashes: [test.blobs[1]!.sha256Hash],
+ });
await expect(
- test.service.getFileContent({
- projectId: "other-project",
- fileId: "file-0",
- }),
- ).rejects.toThrow("Skill file not found");
- expect(test.db.skillFile.findFirst).toHaveBeenLastCalledWith(
- expect.objectContaining({
- where: { projectId: "other-project", id: "file-0" },
- }),
- );
+ test.service.loadResource({ ...input, path: "missing.txt" }),
+ ).rejects.toThrow("Skill resource not found");
+ expect(getFileContents).toHaveBeenCalledOnce();
});
});
diff --git a/web/src/features/public-api/types/unstable-skills.ts b/web/src/features/public-api/types/unstable-skills.ts
new file mode 100644
index 0000000000..772481ee26
--- /dev/null
+++ b/web/src/features/public-api/types/unstable-skills.ts
@@ -0,0 +1,26 @@
+import { SkillVersionFileReferenceSchema } from "@langfuse/shared";
+import { z } from "zod/v4";
+
+export const GetSkillFileContentsInputSchema = z.object({
+ sha256Hashes: z
+ .array(SkillVersionFileReferenceSchema.shape.sha256Hash)
+ .min(1)
+ .max(50),
+});
+
+export const GetSkillFileContentsQuerySchema =
+ GetSkillFileContentsInputSchema.extend({
+ sha256Hashes: z
+ .string()
+ .transform((value) => value.split(","))
+ .pipe(GetSkillFileContentsInputSchema.shape.sha256Hashes),
+ });
+
+export const GetSkillFileContentsResponseSchema = z.object({
+ data: z.array(
+ z.object({
+ sha256Hash: z.string(),
+ content: z.string(),
+ }),
+ ),
+});
diff --git a/web/src/features/skills/README.md b/web/src/features/skills/README.md
index 820a925c22..3e919ce6e0 100644
--- a/web/src/features/skills/README.md
+++ b/web/src/features/skills/README.md
@@ -4,7 +4,7 @@
- `POST /api/public/unstable/skills`
- `GET /api/public/unstable/skills/{skillName}`
- `PATCH /api/public/unstable/skills/{skillName}`
-- `GET /api/public/unstable/skills/files/{fileId}/content`
+- `GET /api/public/unstable/skills/files/content?sha256Hashes=hash1,hash2`
- `PATCH /api/public/unstable/skills/{skillName}/versions/{skillVersion}`
- `DELETE /api/public/unstable/skills/{skillName}/versions/{skillVersion}`
@@ -13,7 +13,7 @@
- Query: `skills.all`
- Query: `skills.filterOptions`
- Query: `skills.byName`
-- Query: `skills.fileContent`
+- Query: `skills.fileContents`
- Query: `skills.skillVersions`
- Mutation: `skills.createVersion`
- Mutation: `skills.setLabels`
diff --git a/web/src/features/skills/actions/createSkillVersion.ts b/web/src/features/skills/actions/createSkillVersion.ts
index 05f1c55086..9c39927217 100644
--- a/web/src/features/skills/actions/createSkillVersion.ts
+++ b/web/src/features/skills/actions/createSkillVersion.ts
@@ -13,8 +13,8 @@ export async function createSkillVersionFromDraft(params: {
const files = Object.values(draft.files);
const input = CreateSkillVersionBodySchema.parse({
files: files.map((file) =>
- file.source
- ? { path: file.path, sha256Hash: file.source.sha256Hash }
+ file.sourceSha !== null && file.currentSha === file.sourceSha
+ ? { path: file.path, sha256Hash: file.sourceSha }
: { path: file.path, content: file.content },
),
commitMessage: draft.commitMessage.trim() || null,
diff --git a/web/src/features/skills/actions/downloadSkillVersion.ts b/web/src/features/skills/actions/downloadSkillVersion.ts
index a01f589095..6c31f3d67b 100644
--- a/web/src/features/skills/actions/downloadSkillVersion.ts
+++ b/web/src/features/skills/actions/downloadSkillVersion.ts
@@ -19,12 +19,12 @@ export async function downloadSkillVersion(params: {
version: number;
}) => Promise<{
createdAt: Date;
- files: Array<{ id: string; path: string }>;
+ files: Array<{ sha256Hash: string; path: string }>;
}>;
- getFileContent: (input: {
+ getFileContents: (input: {
projectId: string;
- fileId: string;
- }) => Promise<{ content: string }>;
+ sha256Hashes: string[];
+ }) => Promise<{ data: Array<{ sha256Hash: string; content: string }> }>;
saveArchive?: (archive: Blob, filename: string) => void;
}): Promise<{ fileCount: number }> {
const skill = await params.getVersion({
@@ -37,11 +37,11 @@ export async function downloadSkillVersion(params: {
await Promise.all(
Array.from({ length: Math.min(4, skill.files.length) }, async () => {
for (const file of pendingFiles) {
- const { content } = await params.getFileContent({
+ const { data } = await params.getFileContents({
projectId: params.projectId,
- fileId: file.id,
+ sha256Hashes: [file.sha256Hash],
});
- files[file.path] = new TextEncoder().encode(content);
+ files[file.path] = new TextEncoder().encode(data[0]!.content);
}
}),
);
diff --git a/web/src/features/skills/actions/importSkillFiles.ts b/web/src/features/skills/actions/importSkillFiles.ts
index cf598a30d6..926aa70f2c 100644
--- a/web/src/features/skills/actions/importSkillFiles.ts
+++ b/web/src/features/skills/actions/importSkillFiles.ts
@@ -7,6 +7,7 @@ import { unzipSync } from "fflate";
import { type FileWithPath } from "react-dropzone";
import { getParentFolderPaths } from "../components/skillFileTree";
import {
+ createSkillDraftFile,
type SkillDraftFile,
type SkillEditorStore,
} from "../components/skillEditorStore";
@@ -44,7 +45,7 @@ export async function importSkillFiles(
if (!result.success) {
throw new Error(`${path}: ${result.error.issues[0]!.message}`);
}
- imports.push({ ...result.data, contentType: "text/plain" });
+ imports.push(createSkillDraftFile(result.data.path, result.data.content));
};
for (const file of files) {
// file-selector prefixes dropped paths with "/" or "./".
@@ -108,7 +109,12 @@ export async function importSkillFiles(
`A file or folder already exists at ${file.path}. No files were added.`,
);
}
- nextFiles[file.path] = file;
+ const existing = nextFiles[file.path];
+ nextFiles[file.path] = {
+ ...file,
+ sourceSha: existing?.sourceSha ?? null,
+ sourceContentLength: existing?.sourceContentLength ?? null,
+ };
}
if (Object.keys(nextFiles).length > MAX_SKILL_FILES) {
throw new Error(`A skill can contain at most ${MAX_SKILL_FILES} files.`);
@@ -116,8 +122,9 @@ export async function importSkillFiles(
const totalBytes = Object.values(nextFiles).reduce(
(total, file) =>
total +
- (file.source?.contentLength ??
- new TextEncoder().encode(file.content).byteLength),
+ (file.content === undefined
+ ? (file.sourceContentLength ?? 0)
+ : new TextEncoder().encode(file.content).byteLength),
0,
);
if (totalBytes > MAX_SKILL_BYTES) {
@@ -132,5 +139,6 @@ export async function importSkillFiles(
activePath: imports[0]!.path,
dirty: true,
});
+ store.getState().actions.hashPendingFiles();
return paths;
}
diff --git a/web/src/features/skills/components/SkillEditor.tsx b/web/src/features/skills/components/SkillEditor.tsx
index 506ab700ac..97d48715ce 100644
--- a/web/src/features/skills/components/SkillEditor.tsx
+++ b/web/src/features/skills/components/SkillEditor.tsx
@@ -30,6 +30,7 @@ import { CreateSkillVersionDialog } from "@/src/features/skills/components/Creat
import { SkillFileExplorer } from "@/src/features/skills/components/SkillFileExplorer";
import { getSkillFileLanguageExtensions } from "@/src/features/skills/utils/getSkillFileLanguageExtensions";
import {
+ createSkillDraftFile,
type SkillDraftFile,
type SkillEditorInitialValue,
type SkillEditorStore,
@@ -267,7 +268,7 @@ export function SkillEditor({
name,
version: baseVersion,
getVersion: (input) => utils.client.skills.byName.query(input),
- getFileContent: (input) => utils.skills.fileContent.fetch(input),
+ getFileContents: (input) => utils.skills.fileContents.fetch(input),
});
capture("skills:version_download", { fileCount: result.fileCount });
} catch {
@@ -585,12 +586,10 @@ export const NEW_SKILL_INITIAL_VALUE: SkillEditorInitialValue = {
labels: [],
tags: [],
files: [
- {
- path: "SKILL.md",
- content:
- "---\nname: my-skill\ndescription: Describe when and how to use this skill.\n---\n\n# Instructions\n\nAdd instructions for the agent here.\n",
- contentType: "text/markdown",
- },
+ createSkillDraftFile(
+ "SKILL.md",
+ "---\nname: my-skill\ndescription: Describe when and how to use this skill.\n---\n\n# Instructions\n\nAdd instructions for the agent here.\n",
+ ),
],
};
diff --git a/web/src/features/skills/components/SkillEditorPage.tsx b/web/src/features/skills/components/SkillEditorPage.tsx
index ee24ebd401..dcb36eeaa0 100644
--- a/web/src/features/skills/components/SkillEditorPage.tsx
+++ b/web/src/features/skills/components/SkillEditorPage.tsx
@@ -158,12 +158,9 @@ export function ExistingSkillPage() {
...skill.data,
files: skill.data.files.map((file) => ({
path: file.path,
- contentType: file.contentType,
- source: {
- fileId: file.id,
- contentLength: file.contentLength,
- sha256Hash: file.sha256Hash,
- },
+ currentSha: file.sha256Hash,
+ sourceSha: file.sha256Hash,
+ sourceContentLength: file.contentLength,
})),
})}
canCreate={canCreate}
diff --git a/web/src/features/skills/components/SkillFileExplorer.tsx b/web/src/features/skills/components/SkillFileExplorer.tsx
index a0cb94a90b..c4f4b13cdf 100644
--- a/web/src/features/skills/components/SkillFileExplorer.tsx
+++ b/web/src/features/skills/components/SkillFileExplorer.tsx
@@ -1,5 +1,6 @@
import { useId, useState, type ReactNode } from "react";
import { useStore } from "zustand";
+import { useShallow } from "zustand/react/shallow";
import {
DndContext,
KeyboardSensor,
@@ -17,12 +18,15 @@ import { CSS } from "@dnd-kit/utilities";
import {
ChevronRight,
Check,
+ Circle,
+ CircleDashed,
File,
FileCode2,
FilePlus2,
Folder,
FolderOpen,
FolderPlus,
+ Plus,
Trash2,
Upload,
X,
@@ -37,6 +41,7 @@ import { Input } from "@/src/components/ui/input";
import { IconButton } from "@/src/components/design-system/IconButton/IconButton";
import { DropdownMenu } from "@/src/components/design-system/DropdownMenu/DropdownMenu";
import { DropzoneController } from "@/src/components/design-system/DropzoneController/DropzoneController";
+import { Tooltip } from "@/src/components/design-system/Tooltip/Tooltip";
import { showErrorToast } from "@/src/features/notifications";
import { importSkillFiles } from "@/src/features/skills/actions/importSkillFiles";
import {
@@ -44,7 +49,10 @@ import {
getParentFolderPaths,
type SkillFileTreeNode,
} from "@/src/features/skills/components/skillFileTree";
-import { type SkillEditorStore } from "@/src/features/skills/components/skillEditorStore";
+import {
+ createSkillDraftFile,
+ type SkillEditorStore,
+} from "@/src/features/skills/components/skillEditorStore";
import { cn } from "@/src/utils/tailwind";
type PendingEntry = {
@@ -62,7 +70,10 @@ export function SkillFileExplorer({
disabled?: boolean;
readOnly?: boolean;
}) {
- const files = useStore(store, (state) => state.files);
+ const filePaths = useStore(
+ store,
+ useShallow((state) => Object.keys(state.files)),
+ );
const folders = useStore(store, (state) => state.folders);
const activePath = useStore(store, (state) => state.activePath);
const actions = useStore(store, (state) => state.actions);
@@ -72,7 +83,7 @@ export function SkillFileExplorer({
);
const [pendingEntry, setPendingEntry] = useState<PendingEntry | null>(null);
const isImporting = useStore(store, (state) => state.isImporting);
- const tree = buildSkillFileTree(Object.keys(files), folders);
+ const tree = buildSkillFileTree(filePaths, folders);
const sensors = useSensors(
useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
useSensor(KeyboardSensor),
@@ -159,10 +170,7 @@ export function SkillFileExplorer({
return;
}
- if (
- pendingEntry.kind === "file" &&
- Object.keys(files).length >= MAX_SKILL_FILES
- ) {
+ if (pendingEntry.kind === "file" && filePaths.length >= MAX_SKILL_FILES) {
showErrorToast(
"Could not add file",
`A skill can contain at most ${MAX_SKILL_FILES} files.`,
@@ -173,11 +181,7 @@ export function SkillFileExplorer({
const created =
pendingEntry.kind === "folder"
? actions.addFolder(path)
- : actions.addFile({
- path,
- content: "",
- contentType: getContentType(path),
- });
+ : actions.addFile(createSkillDraftFile(path, ""));
if (!created) {
showErrorToast(
`${pendingEntry.kind === "folder" ? "Folder" : "File"} already exists`,
@@ -266,6 +270,7 @@ export function SkillFileExplorer({
return (
<DraggableSkillFile
key={node.path}
+ store={store}
path={node.path}
name={node.name}
disabled={moveDisabled}
@@ -460,7 +465,26 @@ const skillMoveCollisionDetection: CollisionDetection = (args) => {
: rectIntersection(candidates);
};
+const fileChangeIndicators = {
+ new: {
+ label: "New file",
+ icon: Plus,
+ className: "text-dark-green h-3.5 w-3.5",
+ },
+ edited: {
+ label: "Edited file",
+ icon: Circle,
+ className: "text-dark-yellow h-2 w-2 fill-current",
+ },
+ pending: {
+ label: "Checking for changes",
+ icon: CircleDashed,
+ className: "text-muted-foreground h-3.5 w-3.5",
+ },
+};
+
function DraggableSkillFile({
+ store,
path,
name,
disabled,
@@ -468,6 +492,7 @@ function DraggableSkillFile({
onSelect,
onDelete,
}: {
+ store: SkillEditorStore;
path: string;
name: string;
disabled: boolean;
@@ -475,6 +500,16 @@ function DraggableSkillFile({
onSelect: () => void;
onDelete: () => void;
}) {
+ const changeStatusId = useId();
+ const changeStatus = useStore(store, (state) => {
+ const file = state.files[path];
+ if (!file) return null;
+ if (file.sourceSha === null) return "new";
+ if (file.currentSha === null) return "pending";
+ return file.currentSha !== file.sourceSha ? "edited" : null;
+ });
+ const indicator = changeStatus ? fileChangeIndicators[changeStatus] : null;
+ const IndicatorIcon = indicator?.icon;
const movable = path !== "SKILL.md";
const draggable = movable && !disabled;
const {
@@ -505,6 +540,15 @@ function DraggableSkillFile({
type="button"
{...(draggable ? attributes : {})}
{...(draggable ? listeners : {})}
+ aria-label={name}
+ aria-describedby={
+ [
+ draggable ? attributes["aria-describedby"] : undefined,
+ indicator ? changeStatusId : undefined,
+ ]
+ .filter(Boolean)
+ .join(" ") || undefined
+ }
onClick={onSelect}
className={cn(
"flex min-w-0 flex-1 items-center gap-2 px-1.5 py-1.5 text-left",
@@ -519,6 +563,25 @@ function DraggableSkillFile({
<span className="min-w-0 flex-1 truncate" title={path}>
{name}
</span>
+ {indicator && IndicatorIcon ? (
+ <Tooltip label={indicator.label}>
+ {({ getTriggerProps }) => (
+ <span
+ {...getTriggerProps()}
+ id={changeStatusId}
+ role="img"
+ aria-label={indicator.label}
+ className="flex h-4 w-4 shrink-0 items-center justify-center"
+ >
+ <IndicatorIcon
+ aria-hidden="true"
+ className={indicator.className}
+ />
+ <span className="sr-only">{indicator.label}</span>
+ </span>
+ )}
+ </Tooltip>
+ ) : null}
</button>
{movable && !disabled ? (
<Button
@@ -663,9 +726,3 @@ function parentFolder(path: string): string {
const separator = path.lastIndexOf("/");
return separator === -1 ? "" : path.slice(0, separator);
}
-
-function getContentType(path: string): string {
- if (path.endsWith(".md")) return "text/markdown";
- if (path.endsWith(".json")) return "application/json";
- return "text/plain";
-}
diff --git a/web/src/features/skills/components/skillEditorStore.ts b/web/src/features/skills/components/skillEditorStore.ts
index 4f98209820..0b339133aa 100644
--- a/web/src/features/skills/components/skillEditorStore.ts
+++ b/web/src/features/skills/components/skillEditorStore.ts
@@ -2,17 +2,29 @@ import { createStore, type StoreApi } from "zustand/vanilla";
import { SkillFilePathSchema } from "@langfuse/shared";
import { getParentFolderPaths } from "./skillFileTree";
import { resetSkillName } from "../utils/resetSkillName";
+import { hashSkillFileContent } from "../utils/hashSkillFileContent";
+import { captureUnknownError } from "@/src/utils/captureUnknownError";
export type SkillDraftFile = {
path: string;
- contentType: string;
-} & (
- | { content: string; source?: never }
- | {
- content?: never;
- source: { fileId: string; contentLength: number; sha256Hash: string };
- }
-);
+ content?: string;
+ currentSha: string | null;
+ sourceSha: string | null;
+ sourceContentLength: number | null;
+};
+
+export function createSkillDraftFile(
+ path: string,
+ content: string,
+): SkillDraftFile {
+ return {
+ path,
+ content,
+ currentSha: null,
+ sourceSha: null,
+ sourceContentLength: null,
+ };
+}
export type SkillEditorInitialValue = {
name: string;
@@ -34,6 +46,7 @@ type SkillEditorState = {
dirty: boolean;
isImporting: boolean;
actions: {
+ hashPendingFiles: () => Promise<void>;
selectFile: (path: string) => void;
updateActiveFile: (content: string) => void;
resetName: () => void;
@@ -61,7 +74,8 @@ export function createSkillEditorStore(
initialValue.files.map(({ path }) => path),
);
- return createStore<SkillEditorState>((set, get) => ({
+ const pendingHashes = new Map<string, Promise<void>>();
+ const store = createStore<SkillEditorState>((set, get) => ({
name: initialValue.name,
baseVersion: initialValue.baseVersion,
files,
@@ -73,37 +87,83 @@ export function createSkillEditorStore(
dirty: false,
isImporting: false,
actions: {
+ hashPendingFiles: async () => {
+ const contents = new Set(
+ Object.values(get().files).flatMap((file) =>
+ file.currentSha === null && file.content !== undefined
+ ? [file.content]
+ : [],
+ ),
+ );
+ await Promise.all(
+ [...contents].map((content) => {
+ const pending = pendingHashes.get(content);
+ if (pending) return pending;
+ const task = hashSkillFileContent(content)
+ .then((currentSha) => {
+ set((state) => {
+ const matchingFiles = Object.entries(state.files).filter(
+ ([, file]) =>
+ file.currentSha === null && file.content === content,
+ );
+ if (!matchingFiles.length) return state;
+ return {
+ files: {
+ ...state.files,
+ ...Object.fromEntries(
+ matchingFiles.map(([path, file]) => [
+ path,
+ { ...file, currentSha },
+ ]),
+ ),
+ },
+ };
+ });
+ })
+ .catch((error: unknown) => {
+ captureUnknownError("skills.hashFileContent", error);
+ })
+ .finally(() => pendingHashes.delete(content));
+ pendingHashes.set(content, task);
+ return task;
+ }),
+ );
+ },
resetName: () => {
const state = get();
const file = state.files["SKILL.md"];
if (!file || file.content === undefined) return;
+ const content = resetSkillName(file.content, state.name);
set({
files: {
...state.files,
"SKILL.md": {
- path: file.path,
- contentType: file.contentType,
- content: resetSkillName(file.content, state.name),
+ ...file,
+ content,
+ currentSha: null,
},
},
dirty: true,
});
+ get().actions.hashPendingFiles();
},
selectFile: (path) => {
if (get().files[path]) set({ activePath: path });
},
- updateActiveFile: (content) =>
+ updateActiveFile: (content) => {
set((state) => ({
files: {
...state.files,
[state.activePath]: {
- path: state.activePath,
- contentType: state.files[state.activePath]!.contentType,
+ ...state.files[state.activePath]!,
content,
+ currentSha: null,
},
},
dirty: true,
- })),
+ }));
+ get().actions.hashPendingFiles();
+ },
addFile: (file) => {
const state = get();
if (hasFilePathConflict(file.path, state.files, state.folders)) {
@@ -120,6 +180,7 @@ export function createSkillEditorStore(
activePath: file.path,
dirty: true,
}));
+ get().actions.hashPendingFiles();
return true;
},
moveFile: (path, targetFolder) => {
@@ -247,6 +308,8 @@ export function createSkillEditorStore(
setCommitMessage: (commitMessage) => set({ commitMessage, dirty: true }),
},
}));
+ store.getState().actions.hashPendingFiles();
+ return store;
}
function hasFileAtOrAbove(
diff --git a/web/src/features/skills/hooks/useSkillFileContents.ts b/web/src/features/skills/hooks/useSkillFileContents.ts
index fda1a624e8..6a59a59f11 100644
--- a/web/src/features/skills/hooks/useSkillFileContents.ts
+++ b/web/src/features/skills/hooks/useSkillFileContents.ts
@@ -2,10 +2,11 @@ import { type SkillDraftFile } from "@/src/features/skills/components/skillEdito
import { api } from "@/src/utils/api";
export function useSkillFileContents(projectId: string, file: SkillDraftFile) {
- return api.skills.fileContent.useQuery(
- { projectId, fileId: file.source?.fileId ?? "" },
+ return api.skills.fileContents.useQuery(
+ { projectId, sha256Hashes: file.sourceSha ? [file.sourceSha] : [] },
{
- enabled: Boolean(file.source),
+ enabled: file.content === undefined && file.sourceSha !== null,
+ select: (response) => response.data[0],
staleTime: Infinity,
gcTime: 10 * 60 * 1000,
meta: { silentAllErrors: true },
diff --git a/web/src/features/skills/server/skill-router.ts b/web/src/features/skills/server/skill-router.ts
index 808f9d979c..162d93d895 100644
--- a/web/src/features/skills/server/skill-router.ts
+++ b/web/src/features/skills/server/skill-router.ts
@@ -16,6 +16,8 @@ import {
import { throwIfNoProjectAccess } from "@/src/features/rbac";
import { SkillService } from "./index";
+import { GetSkillFileContentsInputSchema } from "@/src/features/public-api/types/unstable-skills";
+
const projectInput = z.object({ projectId: z.string() });
export const skillRouter = createTRPCRouter({
@@ -86,15 +88,15 @@ export const skillRouter = createTRPCRouter({
});
}),
- fileContent: protectedProjectProcedure
- .input(projectInput.extend({ fileId: z.string().min(1) }))
+ fileContents: protectedProjectProcedure
+ .input(projectInput.and(GetSkillFileContentsInputSchema))
.query(async ({ input, ctx }) => {
throwIfNoProjectAccess({
session: ctx.session,
projectId: input.projectId,
scope: "skills:read",
});
- return new SkillService(prisma).getFileContent(input);
+ return new SkillService(prisma).getFileContents(input);
}),
skillVersions: protectedProjectProcedure
diff --git a/web/src/features/skills/server/skill-service.ts b/web/src/features/skills/server/skill-service.ts
index 244712516f..52e1aa338c 100644
--- a/web/src/features/skills/server/skill-service.ts
+++ b/web/src/features/skills/server/skill-service.ts
@@ -264,21 +264,49 @@ export class SkillService {
const skill = await this.findSkillVersion(params);
const file = skill.files.find(({ path }) => path === params.path);
if (!file) throw new LangfuseNotFoundError("Skill resource not found");
- return (
- await this.getFileContent({
- projectId: params.projectId,
- fileId: file.id,
- })
- ).content;
+ const { data } = await this.getFileContents({
+ projectId: params.projectId,
+ sha256Hashes: [file.blob.sha256Hash],
+ });
+ return data[0]!.content;
}
- async getFileContent(params: { projectId: string; fileId: string }) {
- const file = await this.prisma.skillFile.findFirst({
- where: { projectId: params.projectId, id: params.fileId },
- select: { blob: { select: { content: true } } },
+ async getFileContents(params: { projectId: string; sha256Hashes: string[] }) {
+ const hashes = [...new Set(params.sha256Hashes)];
+ const where = {
+ projectId: params.projectId,
+ sha256Hash: { in: hashes },
+ files: { some: { projectId: params.projectId } },
+ } satisfies Prisma.SkillBlobWhereInput;
+ const blobs = await this.prisma.skillBlob.findMany({
+ where,
+ select: { contentLength: true },
});
- if (!file) throw new LangfuseNotFoundError("Skill file not found");
- return { content: file.blob.content };
+ if (blobs.length !== hashes.length) {
+ throw new LangfuseNotFoundError("One or more skill files not found");
+ }
+ // Check metadata before loading text so oversized batches stay bounded.
+ if (
+ blobs.reduce((total, blob) => total + blob.contentLength, 0) > 10_000_000
+ ) {
+ throw new InvalidRequestError(
+ "Skill file contents must not exceed 10000000 UTF-8 bytes per batch. Request fewer hashes.",
+ );
+ }
+ const data = await this.prisma.skillBlob.findMany({
+ where,
+ select: { sha256Hash: true, content: true },
+ });
+ if (data.length !== hashes.length) {
+ throw new LangfuseNotFoundError("One or more skill files not found");
+ }
+ const byHash = new Map(data.map((blob) => [blob.sha256Hash, blob]));
+ return {
+ data: hashes.map((sha256Hash) => ({
+ sha256Hash,
+ content: byHash.get(sha256Hash)!.content,
+ })),
+ };
}
async list(params: {
diff --git a/web/src/features/skills/utils/hashSkillFileContent.ts b/web/src/features/skills/utils/hashSkillFileContent.ts
new file mode 100644
index 0000000000..d35a9dbd57
--- /dev/null
+++ b/web/src/features/skills/utils/hashSkillFileContent.ts
@@ -0,0 +1,7 @@
+import { Sha256 } from "@aws-crypto/sha256-browser";
+
+export async function hashSkillFileContent(content: string): Promise<string> {
+ const hash = new Sha256();
+ hash.update(new TextEncoder().encode(content));
+ return btoa(String.fromCharCode(...(await hash.digest())));
+}
diff --git a/web/src/pages/api/public/unstable/skills/files/[fileId]/content.ts b/web/src/pages/api/public/unstable/skills/files/content.ts
similarity index 57%
rename from web/src/pages/api/public/unstable/skills/files/[fileId]/content.ts
rename to web/src/pages/api/public/unstable/skills/files/content.ts
index dedc0dc2c1..8165eb63de 100644
--- a/web/src/pages/api/public/unstable/skills/files/[fileId]/content.ts
+++ b/web/src/pages/api/public/unstable/skills/files/content.ts
@@ -1,24 +1,26 @@
-import { SkillFileContentResponseSchema } from "@langfuse/shared";
import { prisma } from "@langfuse/shared/src/db";
-import { z } from "zod/v4";
import {
createAuthedProjectAPIRoute,
withMiddlewares,
} from "@/src/features/public-api/server";
+import {
+ GetSkillFileContentsQuerySchema,
+ GetSkillFileContentsResponseSchema,
+} from "@/src/features/public-api/types/unstable-skills";
import { SkillService } from "@/src/features/skills/server";
export default withMiddlewares({
GET: createAuthedProjectAPIRoute({
- name: "Get Skill File Content",
+ name: "Get Skill File Contents",
action: "skills:read",
- querySchema: z.object({ fileId: z.string().min(1) }),
- responseSchema: SkillFileContentResponseSchema,
+ querySchema: GetSkillFileContentsQuerySchema,
+ responseSchema: GetSkillFileContentsResponseSchema,
rateLimitResource: "public-api",
fn: async ({ query, auth, res }) => {
res.setHeader("Cache-Control", "no-store");
- return new SkillService(prisma).getFileContent({
+ return new SkillService(prisma).getFileContents({
projectId: auth.scope.projectId,
- fileId: query.fileId,
+ sha256Hashes: query.sha256Hashes,
});
},
}),