@jini-ai/agentic 0.4.3 → 0.4.5

package/dist/skills/install/install-service.d.ts

@@ -1,4 +1,4 @@
-import { type SkillUploadFile } from "./validation.js";
+import { validateSkillFiles, type SkillUploadFile } from "./validation.js";
 import { type GitHubSkillSource } from "./github.js";
 import type { SkillInstallDeps } from "./ports.js";
 export interface ManagedSkill {
@@ -17,7 +17,26 @@ export type SkillInstallInput = {
 } | {
     readonly archiveBase64: string;
 });
+/** A fetched and fully validated skill package, not yet written. Holding the validated bytes (not
+ * the source) means commitSkillInstall writes exactly what was validated, with no second fetch. */
+export interface PreparedSkillInstall {
+    readonly toolId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly source: ManagedSkill["source"];
+    readonly files: ReturnType<typeof validateSkillFiles>["files"];
+}
+/** Fetch/decode and validate before asking for mutation approval. No filesystem writes. */
+export declare function prepareSkillInstall(required: {
+    input: SkillInstallInput;
+    deps: Pick<SkillInstallDeps, "fetch" | "archiveReader" | "yamlReader" | "toolId">;
+}, _optional?: {}): Promise<PreparedSkillInstall>;
 export interface SkillInstaller {
+    prepareSkillInstall(required: SkillInstallInput): Promise<PreparedSkillInstall>;
+    commitSkillInstall(required: {
+        workspaceId: string;
+        prepared: PreparedSkillInstall;
+    }): Promise<ManagedSkill>;
     installSkill(required: SkillInstallInput): Promise<ManagedSkill>;
     listManagedSkills(required: {
         workspaceId: string;

package/dist/skills/install/install-service.js

@@ -3,6 +3,20 @@ import { SkillInputError, validateSkillFiles } from "./validation.js";
 import { readSkillArchive } from "./archive.js";
 import { fetchGitHubSkill } from "./github.js";
 import { readSkillState } from "./state.js";
+/** Fetch/decode and validate before asking for mutation approval. No filesystem writes. */
+export async function prepareSkillInstall(required, _optional = {}) {
+    const { input, deps } = required;
+    let upload;
+    let source = "uploaded";
+    if ("githubUrl" in input)
+        ({ files: upload, source } = await fetchGitHubSkill({ githubUrl: input.githubUrl, fetch: deps.fetch }));
+    else if ("archiveBase64" in input)
+        upload = await readSkillArchive({ base64: input.archiveBase64, archiveReader: deps.archiveReader });
+    else
+        upload = input.files;
+    const validated = validateSkillFiles({ files: upload, yamlReader: deps.yamlReader });
+    return { ...validated, toolId: deps.toolId({ name: validated.name }), source };
+}
 /** Validate before writes; publish via rename, with instance-local queues keyed by resolved root.
  * Cross-process exclusivity remains the host filesystem/layout adapter's responsibility.
  */
@@ -16,6 +30,7 @@ export function createSkillInstaller(deps, optional = {}) {
             throw new SkillInputError({ message: "Invalid skill state file name." });
         return layout;
     };
+    /** Serializes mutations in this server without leaving persistent locks after a crash. */
     async function locked(workspaceId, work) {
         const key = layoutFor(workspaceId).workspaceRoot;
         const result = (queues.get(key) ?? Promise.resolve()).catch(() => { }).then(work);
@@ -47,19 +62,15 @@ export function createSkillInstaller(deps, optional = {}) {
         return directory;
     }
     const changed = async (workspaceId, toolId) => { await optional.onChanged?.({ workspaceId, toolId }); };
-    return {
+    const installer = {
         listManagedSkills,
+        prepareSkillInstall: input => prepareSkillInstall({ input, deps }),
         async installSkill(input) {
-            let upload;
-            let source = "uploaded";
-            if ("githubUrl" in input)
-                ({ files: upload, source } = await fetchGitHubSkill({ githubUrl: input.githubUrl, fetch: deps.fetch }));
-            else if ("archiveBase64" in input)
-                upload = await readSkillArchive({ base64: input.archiveBase64, archiveReader: deps.archiveReader });
-            else
-                upload = input.files;
-            const validated = validateSkillFiles({ files: upload, yamlReader: deps.yamlReader });
-            const toolId = deps.toolId({ name: validated.name });
+            return installer.commitSkillInstall({ workspaceId: input.workspaceId, prepared: await prepareSkillInstall({ input, deps }) });
+        },
+        async commitSkillInstall(input) {
+            const validated = input.prepared;
+            const { toolId, source } = validated;
             const layout = layoutFor(input.workspaceId);
             return locked(input.workspaceId, async () => {
                 if ((await listManagedSkills(input)).some(skill => skill.toolId === toolId))
@@ -112,6 +123,7 @@ export function createSkillInstaller(deps, optional = {}) {
             });
         },
     };
+    return installer;
 }
 function containedDirectory(root, directory) {
     if (!directory || directory === "." || directory === ".." || /[/\\\x00]/.test(directory))

package/dist/skills/install/layout.d.ts

@@ -1,4 +1,12 @@
 import type { SkillLayoutPort } from './ports.js';
+/**
+ * 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
+ * small id-segment guard is duplicated rather than shared, for the same reason
+ * `capability-projection.ts`/`capability-source.ts` already duplicate their own `humanize` helper
+ * between themselves: a private guard belonging to one small module, not a promise to keep two
+ * independent features' internals in sync.
+ */
 /** Every storage location is host-owned; this adapter has no product or cwd defaults.
  * Layout resolves the same required root/stagingRoot/workspaceDirectory/stateFileName
  * contract used by the installer. No site, environment or cwd defaults are allowed: separate

package/dist/skills/install/layout.js

@@ -1,4 +1,26 @@
 import path from 'node:path';
+/**
+ * One safe, indivisible path segment: lowercase alphanumerics in `-`/`.`-separated runs, with no
+ * leading, trailing, or doubled separator. Mirrors `agent-plugins/layout.ts`'s own
+ * `SAFE_ID_SEGMENT_PATTERN` — duplicated rather than imported (see this file's header) — and accepts
+ * this instance's real workspace id (`workspace-local`, per `<site>/uploads/ws/workspace-local/`) as
+ * well as every UUID.
+ */
+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 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
+ * small id-segment guard is duplicated rather than shared, for the same reason
+ * `capability-projection.ts`/`capability-source.ts` already duplicate their own `humanize` helper
+ * 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 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
  * contract used by the installer. No site, environment or cwd defaults are allowed: separate
@@ -13,8 +35,11 @@ export function createSkillLayout(required, _optional = {}) {
     if (!stateFileName || /[/\\\x00]/.test(stateFileName) || ['.', '..', 'SKILL.md', 'README.md', 'LICENSE', 'references', 'scripts', 'assets'].includes(stateFileName))
         throw new Error('Invalid skill state file name.');
     return Object.freeze({ resolve({ workspaceId }) {
+            // Normalize BEFORE validating, not after — see `agent-plugins/layout.ts`'s own comment at the
+            // identical line: the pattern is deliberately lowercase-only, and the normalized value is the
+            // one that actually becomes the path segment, so it is the only value worth asserting about.
             const normalized = workspaceId.toLowerCase();
-            if (normalized.length > 64 || !/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(normalized))
+            if (normalized.length > MAX_ID_SEGMENT_LENGTH || !SAFE_ID_SEGMENT_PATTERN.test(normalized))
                 throw new Error(`resolve: '${workspaceId}' is not a valid workspace id`);
             return { workspaceRoot: path.join(root, workspaceDirectory, normalized), stagingRoot: path.resolve(stagingRoot), stateFileName };
         } });

package/dist/skills/install/live-registration.js

@@ -8,6 +8,7 @@ export function createLiveSkillRegistration(required, _optional = {}) {
     registry.has = input => slots.has(input.id) ? active.has(input.id) : has(input);
     let fingerprint = '';
     return ({ tools }) => {
+        // Discovery changes invalidate the search snapshot; handlers always use current guidance.
         const nextFingerprint = JSON.stringify(tools.map(t => t.descriptor));
         const next = new Map(tools.map(t => [t.descriptor.id, t]));
         if (next.size !== tools.length)

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.d.ts

@@ -1,11 +1,15 @@
 import type { YamlReaderPort } from "./ports.js";
 export type SkillYamlPort = YamlReaderPort;
 export declare class SkillInputError extends Error {
-    constructor({ message }: {
+    constructor(required: {
         message: string;
     }, optional?: {
         cause?: unknown;
     });
+    /** Published host adapters may still use the native Error call shape during migration. */
+    constructor(message: string, optional?: {
+        cause?: unknown;
+    });
 }
 export interface SkillUploadFile {
     readonly path: string;

package/dist/skills/install/validation.js

@@ -1,8 +1,8 @@
 /** Bounded skill-bundle validation; scripts are stored as data and never executed. */
 import path from "node:path";
 export class SkillInputError extends Error {
-    constructor({ message }, optional = {}) {
-        super(message, optional);
+    constructor(required, optional = {}) {
+        super(typeof required === "string" ? required : required.message, optional);
     }
 }
 export const MAX_SKILL_BYTES = 8 * 1024 * 1024;
@@ -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/dist/skills/install/yauzl-archive-reader.d.ts

@@ -0,0 +1,29 @@
+import type { ArchiveReaderPort } from "./ports.js";
+interface ZipEntry {
+    fileName: string;
+    uncompressedSize: number;
+    externalFileAttributes: number;
+}
+interface ZipFile {
+    eachEntry(): AsyncIterable<ZipEntry>;
+    openReadStreamPromise(entry: ZipEntry): Promise<AsyncIterable<Uint8Array> & {
+        destroy(): void;
+    }>;
+    close(): void;
+}
+export interface SkillZipSdkPort {
+    fromBufferPromise(bytes: Buffer, options: {
+        lazyEntries: boolean;
+        strictFileNames: boolean;
+        validateEntrySizes: boolean;
+    }): Promise<ZipFile>;
+}
+/** Bind the installed ZIP library, preserving strict filenames and regular-file-only semantics.
+ * Unlike executable plugin archives, skill scripts are inert data and every non-regular mode is
+ * refused regardless of the ZIP producer's platform marker.
+ */
+export declare function createYauzlSkillArchiveReader({ yauzl }: {
+    yauzl: SkillZipSdkPort;
+}, _optional?: {}): ArchiveReaderPort;
+export {};
+//# sourceMappingURL=yauzl-archive-reader.d.ts.map

package/dist/skills/install/yauzl-archive-reader.js

@@ -0,0 +1,31 @@
+/** Bind the installed ZIP library, preserving strict filenames and regular-file-only semantics.
+ * Unlike executable plugin archives, skill scripts are inert data and every non-regular mode is
+ * refused regardless of the ZIP producer's platform marker.
+ */
+export function createYauzlSkillArchiveReader({ yauzl }, _optional = {}) {
+    return { async open({ bytes }) {
+            const zip = await yauzl.fromBufferPromise(Buffer.from(bytes), { lazyEntries: true, strictFileNames: true, validateEntrySizes: true });
+            return {
+                entries: (async function* () {
+                    for await (const entry of zip.eachEntry()) {
+                        const type = (entry.externalFileAttributes >>> 16) & 0xf000;
+                        const kind = type && type !== 0x8000 && type !== 0x4000 ? "other" : entry.fileName.endsWith("/") ? "directory" : "file";
+                        yield { path: entry.fileName, size: entry.uncompressedSize, kind,
+                            async *read() {
+                                const stream = await zip.openReadStreamPromise(entry);
+                                try {
+                                    for await (const chunk of stream)
+                                        yield chunk;
+                                }
+                                finally {
+                                    stream.destroy();
+                                }
+                            },
+                        };
+                    }
+                })(),
+                close: () => zip.close(),
+            };
+        } };
+}
+//# sourceMappingURL=yauzl-archive-reader.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agentic",
-  "version": "0.4.3",
+  "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,12 +77,12 @@
     "jsdom": "^25.0.1",
     "zod": "^3.25.76",
     "@jini-ai/core": "^0.4.0",
-    "@jini-ai/protocol": "^0.4.2"
+    "@jini-ai/protocol": "^0.4.5"
   },
   "peerDependencies": {
-    "@jini-ai/protocol": "^0.4.1",
+    "@jini-ai/protocol": "^0.4.4",
     "zod": "^3.25.76",
-    "@jini-ai/core": "^0.4.0"
+    "@jini-ai/core": "^0.4.3"
   },
   "peerDependenciesMeta": {
     "@jini-ai/protocol": {