@jini-ai/agentic 0.4.4 → 0.4.5

package/dist/skills/install/archive.js

@@ -3,46 +3,57 @@ import { decodeSkillBase64, MAX_SKILL_BYTES, MAX_SKILL_FILES, MAX_SKILL_FILE_BYT
 export async function readSkillArchive({ base64, archiveReader }, _optional = {}) {
     try {
         const reader = await archiveReader.open({ bytes: decodeSkillBase64({ value: base64 }) });
-        const files = [];
-        let total = 0;
-        let count = 0;
         try {
-            for await (const entry of reader.entries) {
-                if (++count > MAX_SKILL_FILES)
-                    throw new SkillInputError({ message: "A skill archive may contain at most 256 entries." });
-                validateSkillPath({ filePath: entry.path.replace(/\/$/, "") });
-                if (entry.kind !== "file" && entry.kind !== "directory")
-                    throw new SkillInputError({ message: "Skill archives may contain only regular files and directories." });
-                if (entry.kind === "directory")
-                    continue;
-                if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX_SKILL_FILE_BYTES)
-                    throw new SkillInputError({ message: "Skill archive file exceeds 1 MiB." });
-                const chunks = [];
-                let size = 0;
-                {
-                    for await (const chunk of entry.read({})) {
-                        size += chunk.length;
-                        total += chunk.length;
-                        if (size > MAX_SKILL_FILE_BYTES || total > MAX_SKILL_BYTES)
-                            throw new SkillInputError({ message: "Skill archive exceeds its decompressed size limit." });
-                        chunks.push(Buffer.from(chunk));
-                    }
-                }
-                if (size !== entry.size)
-                    throw new SkillInputError({ message: "Skill archive file size does not match its metadata." });
-                files.push({ path: entry.path, contentBase64: Buffer.concat(chunks).toString("base64") });
-            }
-            return files;
+            return await collectArchiveFiles({ entries: reader.entries });
         }
         finally {
             reader.close({});
         }
-        /** Converts malformed archive parser failures into a client-actionable validation refusal. */
     }
     catch (error) {
+        // Converts malformed archive parser failures into a client-actionable validation refusal.
         if (error instanceof SkillInputError)
             throw error;
-        throw new SkillInputError({ message: "Could not read skill ZIP. Use a valid ZIP with regular files only." });
+        throw new SkillInputError({ message: "Could not read skill ZIP. Use a valid ZIP with regular files only." }, { cause: error });
     }
 }
+/** Walks every entry (directories count toward the entry limit) and reads the regular files.
+ * @complexity O(entries + decompressed bytes), bounded to 256 entries and 8 MiB.
+ */
+async function collectArchiveFiles({ entries }) {
+    const files = [];
+    const budget = { total: 0 };
+    let count = 0;
+    for await (const entry of entries) {
+        if (++count > MAX_SKILL_FILES)
+            throw new SkillInputError({ message: "A skill archive may contain at most 256 entries." });
+        if (isRegularFileEntry({ entry }))
+            files.push(await readArchiveFile({ entry, budget }));
+    }
+    return files;
+}
+/** Validates the entry path before its kind; refuses anything but files and directories. */
+function isRegularFileEntry({ entry }) {
+    validateSkillPath({ filePath: entry.path.replace(/\/$/, "") });
+    if (entry.kind !== "file" && entry.kind !== "directory")
+        throw new SkillInputError({ message: "Skill archives may contain only regular files and directories." });
+    return entry.kind === "file";
+}
+/** Streams one file under its own 1 MiB cap and the archive-wide budget, then checks metadata. */
+async function readArchiveFile({ entry, budget }) {
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX_SKILL_FILE_BYTES)
+        throw new SkillInputError({ message: "Skill archive file exceeds 1 MiB." });
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of entry.read({})) {
+        size += chunk.length;
+        budget.total += chunk.length;
+        if (size > MAX_SKILL_FILE_BYTES || budget.total > MAX_SKILL_BYTES)
+            throw new SkillInputError({ message: "Skill archive exceeds its decompressed size limit." });
+        chunks.push(Buffer.from(chunk));
+    }
+    if (size !== entry.size)
+        throw new SkillInputError({ message: "Skill archive file size does not match its metadata." });
+    return { path: entry.path, contentBase64: Buffer.concat(chunks).toString("base64") };
+}
 //# sourceMappingURL=archive.js.map

package/dist/skills/install/github.js

@@ -1,92 +1,131 @@
 /** Commit-pinned public GitHub import with one request/body deadline, byte caps and refused redirects. */
 import { MAX_SKILL_BYTES, MAX_SKILL_FILES, MAX_SKILL_FILE_BYTES, decodeSkillBase64, SkillInputError } from "./validation.js";
+const URL_HELP = "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder.";
+const SHA_PATTERN = /^[a-f0-9]{40}$/;
+const SEGMENT_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+const SKILL_FILE_PATTERN = /^(SKILL\.md|README\.md|LICENSE|(?:references|scripts|assets)\/.*)$/;
+const REGULAR_FILE_MODES = ["100644", "100755"];
 /** Restricts every request to api.github.com, disallows redirects, pins one immutable commit.
  * @complexity O(files + downloaded bytes), at most 256 file requests and 8 MiB decoded content.
  */
 export async function fetchGitHubSkill({ githubUrl, fetch: fetchImpl }, _optional = {}) {
+    const { owner, repo, ref, prefix } = parseGitHubSkillUrl({ githubUrl });
+    const base = `https://api.github.com/repos/${owner}/${repo}`;
+    // One deadline for the whole fetch, including streaming response bodies.
+    const json = createGitHubJsonReader({ fetch: fetchImpl, signal: AbortSignal.timeout(30_000) });
+    const commit = (await json(`${base}/commits/${encodeURIComponent(ref)}`)).sha;
+    if (typeof commit !== "string" || !SHA_PATTERN.test(commit))
+        throw new SkillInputError({ message: "GitHub returned an invalid commit." });
+    const tree = await json(`${base}/git/trees/${commit}?recursive=1`);
+    if (tree.truncated || !Array.isArray(tree.tree))
+        throw new SkillInputError({ message: "GitHub repository tree is incomplete. Choose a smaller skill repository." });
+    const files = await downloadSkillFiles({ rows: tree.tree, prefix, base, json });
+    return { files, source: { githubUrl, commit } };
+}
+/** Accepts only https://github.com/owner/repo[/tree/ref[/folder…]] with plain segments; refuses before any request. */
+function parseGitHubSkillUrl({ githubUrl }) {
     let url;
-    try {
-        url = new URL(githubUrl);
-    }
-    catch {
-        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
-    }
     let parts;
     try {
+        url = new URL(githubUrl);
         parts = url.pathname.replace(/\/$/, "").split("/").slice(1).map(p => decodeURIComponent(p));
     }
-    catch {
-        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    catch (error) {
+        throw new SkillInputError({ message: URL_HELP }, { cause: error });
     }
-    if (url.protocol !== "https:" || url.hostname !== "github.com" || url.port || url.username || url.password || url.search || url.hash || parts.length < 2 || (parts.length > 2 && (parts[2] !== "tree" || parts.length < 4)) || parts.some(p => !/^[a-zA-Z0-9_.-]+$/.test(p) || p === "." || p === ".."))
-        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
-    const owner = parts[0];
+    if (!isGitHubOrigin({ url }) || !isSkillRepoPath({ parts }))
+        throw new SkillInputError({ message: URL_HELP });
     const repo = parts[1].replace(/\.git$/, "");
     if (!repo)
-        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
-    const base = `https://api.github.com/repos/${owner}/${repo}`;
-    // One deadline for the whole fetch, including streaming response bodies.
-    const signal = AbortSignal.timeout(30_000);
-    async function json(endpoint) {
+        throw new SkillInputError({ message: URL_HELP });
+    return { owner: parts[0], repo, ref: parts[3] ?? "HEAD", prefix: parts.length > 4 ? parts.slice(4).join("/") + "/" : "" };
+}
+/** Plain https://github.com with no port, credentials, query or fragment. */
+function isGitHubOrigin({ url }) {
+    return url.protocol === "https:" && url.hostname === "github.com" && !url.port && !url.username && !url.password && !url.search && !url.hash;
+}
+/** owner/repo, or owner/repo/tree/ref[/folder…]; every decoded segment is plain and never `.`/`..`. */
+function isSkillRepoPath({ parts }) {
+    const shapeOk = parts.length === 2 || (parts.length >= 4 && parts[2] === "tree");
+    return shapeOk && parts.every(p => SEGMENT_PATTERN.test(p) && p !== "." && p !== "..");
+}
+/** One JSON endpoint reader sharing the redirect policy, accept header and deadline. */
+function createGitHubJsonReader({ fetch: fetchImpl, signal }) {
+    return async (endpoint) => {
         const response = await fetchImpl({ url: endpoint }, { redirect: "error", signal, headers: { Accept: "application/vnd.github+json" } });
         if (!response.ok)
             throw new SkillInputError({ message: `GitHub could not fetch this skill (HTTP ${response.status}). Use a public repository URL.` });
         if (!response.body)
             throw new SkillInputError({ message: "GitHub returned an empty response." });
-        const reader = response.body.getReader();
-        let bytes = 0;
-        const chunks = [];
-        try {
-            for (;;) {
-                const part = await reader.read();
-                if (part.done)
-                    break;
-                bytes += part.value.length;
-                if (bytes > MAX_SKILL_BYTES * 2)
-                    throw new SkillInputError({ message: "GitHub skill response exceeds its size limit." });
-                chunks.push(part.value);
-            }
-        }
-        finally {
-            await reader.cancel();
-        }
-        const result = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        const result = JSON.parse((await readBoundedBody({ body: response.body })).toString("utf8"));
         if (!result || typeof result !== "object" || Array.isArray(result))
             throw new SkillInputError({ message: "GitHub returned an invalid skill response." });
         return result;
+    };
+}
+/** Streams a response body up to 16 MiB and always releases the reader. */
+async function readBoundedBody({ body }) {
+    const reader = body.getReader();
+    let bytes = 0;
+    const chunks = [];
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            bytes += part.value.length;
+            if (bytes > MAX_SKILL_BYTES * 2)
+                throw new SkillInputError({ message: "GitHub skill response exceeds its size limit." });
+            chunks.push(part.value);
+        }
     }
-    const commit = (await json(`${base}/commits/${encodeURIComponent(parts[3] ?? "HEAD")}`)).sha;
-    if (typeof commit !== "string" || !/^[a-f0-9]{40}$/.test(commit))
-        throw new SkillInputError({ message: "GitHub returned an invalid commit." });
-    const tree = await json(`${base}/git/trees/${commit}?recursive=1`);
-    if (tree.truncated || !Array.isArray(tree.tree))
-        throw new SkillInputError({ message: "GitHub repository tree is incomplete. Choose a smaller skill repository." });
-    const prefix = parts.length > 4 ? parts.slice(4).join("/") + "/" : "";
+    finally {
+        await reader.cancel();
+    }
+    return Buffer.concat(chunks);
+}
+/** Checks each selected row, then fetches its blob, in tree order, under declared and decoded budgets. */
+async function downloadSkillFiles({ rows, prefix, base, json }) {
     const files = [];
-    let total = 0;
-    let actualBytes = 0;
-    for (const row of tree.tree) {
-        if (typeof row.path !== "string" || !row.path.startsWith(prefix))
+    const budget = { declared: 0, actual: 0 };
+    for (const row of rows) {
+        const relative = selectSkillRow({ row, prefix });
+        if (relative === undefined)
             continue;
-        const relative = row.path.slice(prefix.length);
-        if (!/^(SKILL\.md|README\.md|LICENSE|(?:references|scripts|assets)\/.*)$/.test(relative) || row.type === "tree")
-            continue;
-        if (row.type !== "blob" || !["100644", "100755"].includes(String(row.mode)))
-            throw new SkillInputError({ message: "GitHub skills may contain only regular files." });
-        if (typeof row.size !== "number" || row.size < 0 || row.size > MAX_SKILL_FILE_BYTES || typeof row.sha !== "string" || !/^[a-f0-9]{40}$/.test(row.sha))
-            throw new SkillInputError({ message: "GitHub skill file exceeds its size limit or has invalid metadata." });
-        total += row.size;
-        if (total > MAX_SKILL_BYTES || files.length >= MAX_SKILL_FILES)
-            throw new SkillInputError({ message: "GitHub skill exceeds 8 MiB or 256 files." });
-        const blob = await json(`${base}/git/blobs/${row.sha}`);
-        if (blob.encoding !== "base64" || typeof blob.content !== "string")
-            throw new SkillInputError({ message: "GitHub returned an invalid skill file." });
-        const contentBase64 = blob.content.replace(/\s/g, "");
-        actualBytes += decodeSkillBase64({ value: contentBase64 }, { maxBytes: MAX_SKILL_FILE_BYTES }).length;
-        if (actualBytes > MAX_SKILL_BYTES)
+        const { size, sha } = readRegularBlobRow({ row });
+        budget.declared += size;
+        if (budget.declared > MAX_SKILL_BYTES || files.length >= MAX_SKILL_FILES)
             throw new SkillInputError({ message: "GitHub skill exceeds 8 MiB or 256 files." });
-        files.push({ path: relative, contentBase64 });
+        files.push({ path: relative, contentBase64: await downloadBlob({ url: `${base}/git/blobs/${sha}`, json, budget }) });
     }
-    return { files, source: { githubUrl, commit } };
+    return files;
+}
+/** Path relative to the skill folder when the row is an allowed skill file, else undefined (skipped). */
+function selectSkillRow({ row, prefix }) {
+    if (typeof row.path !== "string" || !row.path.startsWith(prefix))
+        return undefined;
+    const relative = row.path.slice(prefix.length);
+    if (!SKILL_FILE_PATTERN.test(relative) || row.type === "tree")
+        return undefined;
+    return relative;
+}
+/** Refuses non-regular entries (submodules, symlinks) and missing or oversized metadata. */
+function readRegularBlobRow({ row }) {
+    if (row.type !== "blob" || !REGULAR_FILE_MODES.includes(String(row.mode)))
+        throw new SkillInputError({ message: "GitHub skills may contain only regular files." });
+    if (typeof row.size !== "number" || row.size < 0 || row.size > MAX_SKILL_FILE_BYTES || typeof row.sha !== "string" || !SHA_PATTERN.test(row.sha))
+        throw new SkillInputError({ message: "GitHub skill file exceeds its size limit or has invalid metadata." });
+    return { size: row.size, sha: row.sha };
+}
+/** Fetches one base64 blob, enforcing the 1 MiB file cap and 8 MiB decoded total. */
+async function downloadBlob({ url, json, budget }) {
+    const blob = await json(url);
+    if (blob.encoding !== "base64" || typeof blob.content !== "string")
+        throw new SkillInputError({ message: "GitHub returned an invalid skill file." });
+    const contentBase64 = blob.content.replace(/\s/g, "");
+    budget.actual += decodeSkillBase64({ value: contentBase64 }, { maxBytes: MAX_SKILL_FILE_BYTES }).length;
+    if (budget.actual > MAX_SKILL_BYTES)
+        throw new SkillInputError({ message: "GitHub skill exceeds 8 MiB or 256 files." });
+    return contentBase64;
 }
 //# sourceMappingURL=github.js.map

package/dist/skills/install/layout.js

@@ -9,8 +9,8 @@ import path from 'node:path';
 const SAFE_ID_SEGMENT_PATTERN = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
 /** Bounds the segment so a caller cannot drive a pathological path length. */
 const MAX_ID_SEGMENT_LENGTH = 64;
-// The segment grammar above moved from Tovu features/skills/layout.ts; the sibling path in its
-// historical rationale refers to Tovu features/agent-plugins/layout.ts.
+// The segment grammar above moved from host features/skills/layout.ts; the sibling path in its
+// historical rationale refers to host features/agent-plugins/layout.ts.
 /**
  * Deliberately does NOT import anything from `src/features/agent-plugins/` — Agent Skills and Agent
  * Plugins are different things with their own directories (owner decision, above), and this file's
@@ -19,7 +19,7 @@ const MAX_ID_SEGMENT_LENGTH = 64;
  * between themselves: a private guard belonging to one small module, not a promise to keep two
  * independent features' internals in sync.
  */
-// This paragraph records the original Tovu module boundary; the private segment guard now
+// This paragraph records the original host module boundary; the private segment guard now
 // belongs to this Jini layout owner, and the host keeps only the site-directory adapter.
 /** Every storage location is host-owned; this adapter has no product or cwd defaults.
  * Layout resolves the same required root/stagingRoot/workspaceDirectory/stateFileName

package/dist/skills/install/node-filesystem.js

@@ -33,7 +33,9 @@ export function createNodeSkillFilesystem(_required, _optional = {}) {
                 await handle.close();
             }
         },
-        writeFile: ({ path, bytes, exclusive, mode }) => writeFile(path, bytes, { flag: exclusive ? 'wx' : 'w', mode }),
+        // The port types `exclusive` as the literal `true`: skill files and state temporaries are only
+        // ever created, never overwritten in place, so the flag is always exclusive-create.
+        writeFile: ({ path, bytes, mode }) => writeFile(path, bytes, { flag: 'wx', mode }),
         rename: ({ from, to }) => rename(from, to),
         remove: ({ path }, options = {}) => rm(path, options),
     };

package/dist/skills/install/state.js

@@ -1,17 +1,19 @@
 import path from "node:path";
+const MAX_STATE_BYTES = 8192;
+const INVALID_STATE = "Invalid skill installation record.";
 /** Missing legacy records default to enabled; malformed records and symlinks fail closed. */
 export async function readSkillState(required, _optional = {}) {
     const statePath = path.join(required.directory, required.stateFileName);
     try {
         const info = await required.filesystem.lstat({ path: statePath });
-        if (info.kind !== "file" || info.size > 8192)
-            throw new Error("Invalid skill installation record.");
-        const bytes = await required.filesystem.readFile({ path: statePath, maxBytes: 8192 });
-        if (bytes.length > 8192)
-            throw new Error("Invalid skill installation record.");
+        if (info.kind !== "file" || info.size > MAX_STATE_BYTES)
+            throw new Error(INVALID_STATE);
+        const bytes = await required.filesystem.readFile({ path: statePath, maxBytes: MAX_STATE_BYTES });
+        if (bytes.length > MAX_STATE_BYTES)
+            throw new Error(INVALID_STATE);
         const state = JSON.parse(Buffer.from(bytes).toString("utf8"));
-        if (!state || typeof state.enabled !== "boolean" || (state.source !== "uploaded" && (!state.source || typeof state.source.githubUrl !== "string" || !/^[a-f0-9]{40}$/.test(state.source.commit))))
-            throw new Error("Invalid skill installation record.");
+        if (!isSkillState(state))
+            throw new Error(INVALID_STATE);
         return state;
     }
     catch (error) {
@@ -20,4 +22,13 @@ export async function readSkillState(required, _optional = {}) {
         throw error;
     }
 }
+/** A boolean `enabled` plus either "uploaded" or a GitHub source pinned to a 40-hex commit. */
+function isSkillState(value) {
+    const state = value;
+    if (!state || typeof state.enabled !== "boolean")
+        return false;
+    if (state.source === "uploaded")
+        return true;
+    return !!state.source && typeof state.source.githubUrl === "string" && /^[a-f0-9]{40}$/.test(state.source.commit);
+}
 //# sourceMappingURL=state.js.map

package/dist/skills/install/validation.js

@@ -10,6 +10,10 @@ export const MAX_SKILL_FILES = 256;
 export const MAX_SKILL_FILE_BYTES = 1024 * 1024;
 const TEXT_EXTENSIONS = new Set([".md", ".txt", ".json", ".yaml", ".yml", ".csv", ".svg", ".sh", ".py", ".js", ".ts", ".mjs"]);
 const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp"]);
+const ROOT_FILES = new Set(["SKILL.md", "README.md", "LICENSE"]);
+const SKILL_FOLDERS = new Set(["references", "scripts", "assets"]);
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const MISSING_FRONTMATTER = "SKILL.md must have YAML frontmatter with a name and description.";
 /** Decodes bounded canonical base64; malformed encodings never silently turn into empty files. */
 export function decodeSkillBase64({ value }, { maxBytes = MAX_SKILL_BYTES } = {}) {
     if (typeof value !== "string" || value.length > Math.ceil(maxBytes / 3) * 4)
@@ -27,24 +31,28 @@ export function validateSkillPath({ filePath }, _optional = {}) {
 }
 /** Strict frontmatter for new installs; the legacy disk loader remains backwards compatible. */
 export function validateSkillMarkdown({ markdown, yamlReader }, _optional = {}) {
+    const { name, description } = readFrontmatterFields({ markdown, yamlReader });
+    if (typeof name !== "string" || typeof description !== "string" || !description.trim())
+        throw new SkillInputError({ message: MISSING_FRONTMATTER });
+    if (name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+        throw new SkillInputError({ message: "Skill name must use lowercase letters, digits and single hyphens (1–64 characters)." });
+    if (description.length > 1024)
+        throw new SkillInputError({ message: "Skill description exceeds 1024 characters." });
+    return { name, description: description.replace(/\s+/g, " ").trim() };
+}
+/** Parses the leading `---` block through the host YAML port; a non-object result has no fields. */
+function readFrontmatterFields({ markdown, yamlReader }) {
     const frontmatter = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
     if (!frontmatter)
-        throw new SkillInputError({ message: "SKILL.md must have YAML frontmatter with a name and description." });
+        throw new SkillInputError({ message: MISSING_FRONTMATTER });
     let fields;
     try {
         fields = yamlReader.read({ yaml: frontmatter[1] });
     }
-    catch {
-        throw new SkillInputError({ message: "SKILL.md must have valid YAML frontmatter." });
+    catch (error) {
+        throw new SkillInputError({ message: "SKILL.md must have valid YAML frontmatter." }, { cause: error });
     }
-    const { name, description } = (fields && typeof fields === "object" ? fields : {});
-    if (typeof name !== "string" || typeof description !== "string" || !description.trim())
-        throw new SkillInputError({ message: "SKILL.md must have YAML frontmatter with a name and description." });
-    if (name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
-        throw new SkillInputError({ message: "Skill name must use lowercase letters, digits and single hyphens (1–64 characters)." });
-    if (description.length > 1024)
-        throw new SkillInputError({ message: "Skill description exceeds 1024 characters." });
-    return { name, description: description.replace(/\s+/g, " ").trim() };
+    return (fields && typeof fields === "object" ? fields : {});
 }
 /** Validates the whole package before writes, including cross-file collisions and combined limits.
  * @complexity O(total bytes + files × path length), bounded to 8 MiB / 256 files.
@@ -54,51 +62,76 @@ export function validateSkillFiles({ files: upload, yamlReader }, _optional = {}
         throw new SkillInputError({ message: "A skill must contain 1–256 files." });
     for (const file of upload)
         validateSkillPath({ filePath: file.path });
+    const prefix = selectSkillFolder({ upload });
+    const files = new Map();
+    const budget = { total: 0 };
+    for (const file of upload) {
+        const { relative, bytes } = validateBundleFile({ file, prefix, seen: files, budget });
+        files.set(relative, bytes);
+    }
+    return { ...validateSkillMarkdown({ markdown: files.get("SKILL.md").toString("utf8"), yamlReader }), files };
+}
+/** The folder holding the bundle's only SKILL.md (empty string at the root). */
+function selectSkillFolder({ upload }) {
     const skillFiles = upload.filter(f => f.path === "SKILL.md" || f.path.endsWith("/SKILL.md"));
     if (skillFiles.length !== 1) {
         if (skillFiles.length > 1 && new Set(skillFiles.map(f => f.path)).size === 1)
             throw new SkillInputError({ message: `Duplicate skill file path: ${skillFiles[0].path}` });
         throw new SkillInputError({ message: "Choose one skill folder containing a single SKILL.md." });
     }
-    const prefix = skillFiles[0].path.slice(0, -"SKILL.md".length);
-    const files = new Map();
-    let total = 0;
-    for (const file of upload) {
-        if (!file.path.startsWith(prefix))
-            throw new SkillInputError({ message: "All files must belong to the selected skill folder." });
-        const relative = file.path.slice(prefix.length);
-        validateSkillPath({ filePath: relative });
-        if (files.has(relative))
-            throw new SkillInputError({ message: `Duplicate skill file path: ${relative}` });
-        const extension = path.posix.extname(relative).toLowerCase();
-        const top = relative.split("/")[0];
-        if (relative !== "SKILL.md" && relative !== "README.md" && relative !== "LICENSE" && !["references", "scripts", "assets"].includes(top))
-            throw new SkillInputError({ message: `Unsupported skill file location: ${relative}` });
-        if (relative !== "LICENSE" && !TEXT_EXTENSIONS.has(extension) && !(top === "assets" && ASSET_EXTENSIONS.has(extension)))
-            throw new SkillInputError({ message: `Unsupported skill file type: ${relative}` });
-        const bytes = decodeSkillBase64({ value: file.contentBase64 }, { maxBytes: MAX_SKILL_FILE_BYTES });
-        if (relative === "SKILL.md" && bytes.length > 128 * 1024)
-            throw new SkillInputError({ message: "SKILL.md exceeds 128 KiB." });
-        total += bytes.length;
-        if (total > MAX_SKILL_BYTES)
-            throw new SkillInputError({ message: "Skill files exceed 8 MiB combined." });
-        if (TEXT_EXTENSIONS.has(extension) || relative === "LICENSE") {
-            try {
-                new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-            }
-            catch {
-                throw new SkillInputError({ message: `Skill text file must be valid UTF-8 without null bytes: ${relative}` });
-            }
-            if (bytes.includes(0))
-                throw new SkillInputError({ message: `Skill text file must be valid UTF-8 without null bytes: ${relative}` });
-        }
-        else {
-            const valid = extension === ".png" ? bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) : extension === ".webp" ? bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP" : bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
-            if (!valid)
-                throw new SkillInputError({ message: `Skill asset content does not match its file type: ${relative}` });
-        }
-        files.set(relative, bytes);
+    return skillFiles[0].path.slice(0, -"SKILL.md".length);
+}
+/** Checks one upload's folder, path, location, type, sizes and content; returns its folder-relative key. */
+function validateBundleFile({ file, prefix, seen, budget }) {
+    if (!file.path.startsWith(prefix))
+        throw new SkillInputError({ message: "All files must belong to the selected skill folder." });
+    const relative = file.path.slice(prefix.length);
+    validateSkillPath({ filePath: relative });
+    if (seen.has(relative))
+        throw new SkillInputError({ message: `Duplicate skill file path: ${relative}` });
+    const { extension, isText } = classifySkillFile({ relative });
+    const bytes = decodeSkillBase64({ value: file.contentBase64 }, { maxBytes: MAX_SKILL_FILE_BYTES });
+    if (relative === "SKILL.md" && bytes.length > 128 * 1024)
+        throw new SkillInputError({ message: "SKILL.md exceeds 128 KiB." });
+    budget.total += bytes.length;
+    if (budget.total > MAX_SKILL_BYTES)
+        throw new SkillInputError({ message: "Skill files exceed 8 MiB combined." });
+    if (isText)
+        assertTextContent({ relative, bytes });
+    else if (!matchesAssetSignature({ extension, bytes }))
+        throw new SkillInputError({ message: `Skill asset content does not match its file type: ${relative}` });
+    return { relative, bytes };
+}
+/** Allowed locations are SKILL.md, README.md, LICENSE and the references/scripts/assets folders;
+ * text extensions anywhere there, image extensions only under assets/. */
+function classifySkillFile({ relative }) {
+    const extension = path.posix.extname(relative).toLowerCase();
+    const top = relative.split("/")[0];
+    if (!ROOT_FILES.has(relative) && !SKILL_FOLDERS.has(top))
+        throw new SkillInputError({ message: `Unsupported skill file location: ${relative}` });
+    const isText = relative === "LICENSE" || TEXT_EXTENSIONS.has(extension);
+    if (!isText && !(top === "assets" && ASSET_EXTENSIONS.has(extension)))
+        throw new SkillInputError({ message: `Unsupported skill file type: ${relative}` });
+    return { extension, isText };
+}
+/** Text files must be strict UTF-8 with no NUL bytes. */
+function assertTextContent({ relative, bytes }) {
+    const message = `Skill text file must be valid UTF-8 without null bytes: ${relative}`;
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     }
-    return { ...validateSkillMarkdown({ markdown: files.get("SKILL.md").toString("utf8"), yamlReader }), files };
+    catch (error) {
+        throw new SkillInputError({ message }, { cause: error });
+    }
+    if (bytes.includes(0))
+        throw new SkillInputError({ message });
+}
+/** Magic-byte sniffing for the allowed image types (.png, .webp, otherwise JPEG). */
+function matchesAssetSignature({ extension, bytes }) {
+    if (extension === ".png")
+        return bytes.subarray(0, 8).equals(PNG_SIGNATURE);
+    if (extension === ".webp")
+        return bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP";
+    return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
 }
 //# sourceMappingURL=validation.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agentic",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Framework-free agent-control layer: page-capability vocabulary and manifests, the data-agent-* markup convention, AG-UI projection, generative-UI streams, and A2UI.",
   "license": "Apache-2.0",
   "repository": {
@@ -77,7 +77,7 @@
     "jsdom": "^25.0.1",
     "zod": "^3.25.76",
     "@jini-ai/core": "^0.4.0",
-    "@jini-ai/protocol": "^0.4.4"
+    "@jini-ai/protocol": "^0.4.5"
   },
   "peerDependencies": {
     "@jini-ai/protocol": "^0.4.4",