@jini-ai/agentic 0.4.3 → 0.4.5

package/dist/core/site-guide/site-guide.js

@@ -0,0 +1,162 @@
+const MINIMAL_TOPICS = [{
+        id: 'site', title: 'How this site works', summary: 'Learn the available building blocks before planning or building.',
+        explanation: 'Read the live facts, then consult the host topics and their tools. Missing or forbidden facts are unknown, not disabled capabilities.',
+        permissions: [], pointers: [], workflows: [],
+    }];
+export class SiteGuideInputError extends Error {
+    constructor({ message }, _options = {}) { super(message); this.name = 'SiteGuideInputError'; }
+}
+/** Bound an injected read so an unavailable extension cannot hang learning. Always clear timers.
+ * @complexity O(1) beyond the supplied read; rejection text is kept internal to the shell.
+ */
+async function boundedRead(read, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([Promise.resolve().then(read), new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('site guide read timed out')), timeoutMs);
+            })]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Compose by topic id. Core cards keep their owner; plugins add distinct, permission-gated topics.
+ * @complexity O(t) in bounded built-in and contributed topic counts, O(t) lookup space.
+ */
+function combineTopics(builtIns, contributions) {
+    const topics = new Map(builtIns.map(topic => [topic.id, { topic, source: 'core' }]));
+    const byId = new Map();
+    for (const contribution of contributions) {
+        for (const topic of contribution.topics) {
+            const candidates = byId.get(topic.id) ?? [];
+            candidates.push({ topic, pluginId: contribution.pluginId });
+            byId.set(topic.id, candidates);
+        }
+    }
+    let conflicts = false;
+    for (const [id, candidates] of byId) {
+        // A contribution cannot replace a host's prose, pointers, workflows or security gates.
+        if (topics.has(id) || candidates.length !== 1) {
+            conflicts = true;
+            continue;
+        }
+        const candidate = candidates[0];
+        topics.set(id, { topic: candidate.topic, source: candidate.pluginId });
+    }
+    return { topics: [...topics.values()], conflicts };
+}
+/** Build a neutral read-only guide over host ports. No product state or plugin loader is ambient.
+ * Authorization and contributions are read fresh for each request. Errors from enrichment/facts
+ * yield explicit unavailable status without copying arbitrary error messages into model context.
+ * @param ports - Facts, authorization, optional enrichment, and host minimal capability cards.
+ * @returns One overview/explain service. Invalid input and hidden topics throw SiteGuideInputError.
+ * @complexity O(t + p) per request, topics plus distinct permissions; one bulk facts read.
+ * @example createSiteGuide({ facts, authorize, builtInTopics: cards }).run({ caller, operation: 'overview' });
+ */
+export function createSiteGuide(ports, options = {}) {
+    const timeoutMs = options.readTimeoutMs ?? 5_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new SiteGuideInputError({ message: 'readTimeoutMs must be a positive finite number' });
+    const builtIns = ports.builtInTopics ?? MINIMAL_TOPICS;
+    if (builtIns.length > 256 || new Set(builtIns.map(topic => topic.id)).size !== builtIns.length)
+        throw new SiteGuideInputError({ message: 'Built-in topics must have unique ids and contain at most 256 cards' });
+    return { async run(input, _options = {}) {
+            assertGuideInput(input);
+            const loaded = await loadContributions({ ports, caller: input.caller, timeoutMs });
+            const combined = combineTopics(builtIns, loaded.contributions);
+            const enrichment = combined.conflicts ? 'partial' : loaded.enrichment;
+            const gate = createPermissionGate({ ports, caller: input.caller, timeoutMs });
+            const views = await buildViews({ topics: combined.topics, input, permitted: gate.permitted });
+            if (input.operation === 'explain' && views.length === 0)
+                throw new SiteGuideInputError({ message: 'Topic unavailable. Call site_guide with operation overview for topics you may read.' });
+            // Overview is discovery only; read fresh domain facts when a visible topic is explained.
+            const facts = input.operation === 'explain' ? await readFacts({ ports, caller: input.caller, topicIds: views.map(view => view.id), timeoutMs }) : {};
+            return { operation: input.operation, topics: views, facts, callerPermissions: await gate.granted(), enrichment };
+        } };
+}
+/** Refuses unknown operations, a topic on overview, and explain without a well-formed topic id. */
+function assertGuideInput(input) {
+    if (input.operation !== 'overview' && input.operation !== 'explain')
+        throw new SiteGuideInputError({ message: 'operation must be overview or explain' });
+    if (input.operation === 'overview' && input.topic !== undefined)
+        throw new SiteGuideInputError({ message: 'topic is only accepted with operation explain' });
+    if (input.operation === 'explain' && (typeof input.topic !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(input.topic))) {
+        throw new SiteGuideInputError({ message: 'explain requires a topic id from overview' });
+    }
+}
+/** Reads plugin contributions within the deadline; any failure or over-limit result degrades to none. */
+async function loadContributions({ ports, caller, timeoutMs }) {
+    if (!ports.loadContributions)
+        return { contributions: [], enrichment: 'ok' };
+    try {
+        const loaded = await boundedRead(() => ports.loadContributions({ caller }), timeoutMs);
+        if (loaded.items.reduce((count, item) => count + item.topics.length, 0) > 256)
+            throw new SiteGuideInputError({ message: 'Too many contributed topics' });
+        return { contributions: loaded.items, enrichment: loaded.refusals.length ? 'partial' : 'ok' };
+    }
+    catch {
+        return { contributions: [], enrichment: 'unavailable' };
+    }
+}
+/** Per-request authorization cache: each permission is asked at most once, in first-use order. */
+function createPermissionGate({ ports, caller, timeoutMs }) {
+    const decisions = new Map();
+    const allowed = (permission) => {
+        let decision = decisions.get(permission);
+        if (!decision) {
+            // Failed authorization is denial, never an excuse to expose a card or run its read.
+            decision = boundedRead(() => ports.authorize({ caller, permission }), timeoutMs).catch(() => false);
+            decisions.set(permission, decision);
+        }
+        return decision;
+    };
+    return {
+        permitted: async (permissions) => (await Promise.all(permissions.map(allowed))).every(Boolean),
+        granted: async () => {
+            const callerPermissions = [];
+            for (const [permission, decision] of decisions)
+                if (await decision)
+                    callerPermissions.push(permission);
+            return callerPermissions;
+        },
+    };
+}
+/** Visible cards in topic order; explain narrows to the requested id and adds its permitted details. */
+async function buildViews({ topics, input, permitted }) {
+    const views = [];
+    for (const entry of topics) {
+        if (input.operation === 'explain' && entry.topic.id !== input.topic)
+            continue;
+        if (!await permitted(entry.topic.permissions))
+            continue;
+        const view = { id: entry.topic.id, title: entry.topic.title, summary: entry.topic.summary, source: entry.source };
+        views.push(input.operation === 'explain' ? await explainView({ view, topic: entry.topic, permitted }) : view);
+    }
+    return views;
+}
+async function explainView({ view, topic, permitted }) {
+    const pointers = await withoutForbidden({ items: topic.pointers, permitted });
+    const workflows = await withoutForbidden({ items: topic.workflows, permitted });
+    return { ...view, explanation: topic.explanation, pointers, workflows };
+}
+/** Keeps items whose permissions are all granted, asked one item at a time, minus their gates. */
+async function withoutForbidden({ items, permitted }) {
+    const kept = [];
+    for (const { permissions, ...item } of items)
+        if (await permitted(permissions))
+            kept.push(item);
+    return kept;
+}
+/** One bulk facts read for the visible topics; failure marks each of them unavailable. */
+async function readFacts({ ports, caller, topicIds, timeoutMs }) {
+    try {
+        const read = await boundedRead(() => ports.facts.read({ caller, topics: topicIds }), timeoutMs);
+        // A facts adapter returning an unrelated section cannot disclose it through this tool.
+        return Object.fromEntries(topicIds.map(id => [id, read[id] ?? { status: 'unavailable' }]));
+    }
+    catch {
+        return Object.fromEntries(topicIds.map(id => [id, { status: 'unavailable' }]));
+    }
+}
+//# sourceMappingURL=site-guide.js.map

package/dist/core/site-guide/topic-schema.d.ts

@@ -0,0 +1,16 @@
+import type { GuideTopic } from './types.js';
+/** Parse bounded data-only enrichment. Invalid fields and duplicate ids refuse the whole file.
+ * @returns Validated topics or a fixed, data-free diagnostic; never quotes plugin bytes.
+ * @complexity O(n) characters, capped at 256 KiB of UTF-8, plus bounded shape traversal.
+ * @example parseGuideTopics({ raw: '{"version":1,"topics":[]}' });
+ */
+export declare function parseGuideTopics({ raw }: {
+    readonly raw: string;
+}, _options?: Record<string, never>): {
+    readonly ok: true;
+    readonly descriptors: readonly GuideTopic[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+//# sourceMappingURL=topic-schema.d.ts.map

package/dist/core/site-guide/topic-schema.js

@@ -0,0 +1,68 @@
+/** Native shape guards keep the core barrel usable without the optional A2UI/Zod peer. */
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value, maximum = 8_000) {
+    return typeof value === 'string' && value.length > 0 && value.length <= maximum;
+}
+function keys(value, permitted) {
+    return Object.keys(value).every(key => permitted.includes(key));
+}
+function list(value, maximum, guard) {
+    return Array.isArray(value) && value.length <= maximum && value.every(guard);
+}
+function permission(value) { return text(value, 128); }
+function permissions(value) { return list(value, 32, permission); }
+function step(value) { return text(value); }
+/** Accept document/admin/HTTPS pointers, never script URLs or arbitrary local files. */
+function href(value) {
+    return text(value, 512) && (value.startsWith('/admin/') || value.startsWith('development/') || value.startsWith('https://'));
+}
+function pointer(value) {
+    if (!record(value) || !keys(value, ['label', 'tool', 'href', 'permissions']))
+        return false;
+    if (!text(value.label) || !permissions(value.permissions))
+        return false;
+    if (value.tool !== undefined && !text(value.tool, 128))
+        return false;
+    if (value.href !== undefined && !href(value.href))
+        return false;
+    return value.tool !== undefined || value.href !== undefined;
+}
+function workflow(value) {
+    if (!record(value) || !keys(value, ['title', 'steps', 'permissions']))
+        return false;
+    return text(value.title) && permissions(value.permissions) && list(value.steps, 16, step) && value.steps.length > 0;
+}
+function topic(value) {
+    if (!record(value) || !keys(value, ['id', 'title', 'summary', 'explanation', 'permissions', 'pointers', 'workflows']))
+        return false;
+    if (!text(value.id, 64) || !/^[a-z][a-z0-9-]*$/.test(value.id))
+        return false;
+    return text(value.title, 128) && text(value.summary, 1_000) && text(value.explanation) && permissions(value.permissions)
+        && list(value.pointers, 24, pointer) && list(value.workflows, 16, workflow);
+}
+/** Parse bounded data-only enrichment. Invalid fields and duplicate ids refuse the whole file.
+ * @returns Validated topics or a fixed, data-free diagnostic; never quotes plugin bytes.
+ * @complexity O(n) characters, capped at 256 KiB of UTF-8, plus bounded shape traversal.
+ * @example parseGuideTopics({ raw: '{"version":1,"topics":[]}' });
+ */
+export function parseGuideTopics({ raw }, _options = {}) {
+    if (raw.length > 262_144 || new TextEncoder().encode(raw).byteLength > 262_144)
+        return { ok: false, reason: 'site-guide manifest exceeds 256 KiB' };
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'site-guide manifest must be valid JSON' };
+    }
+    if (!record(value) || !keys(value, ['version', 'topics']) || value.version !== 1 || !list(value.topics, 64, topic)) {
+        return { ok: false, reason: 'site-guide manifest does not match version 1 topic schema' };
+    }
+    const ids = new Set(value.topics.map(item => item.id));
+    if (ids.size !== value.topics.length)
+        return { ok: false, reason: 'site-guide manifest contains duplicate topic ids' };
+    return { ok: true, descriptors: value.topics };
+}
+//# sourceMappingURL=topic-schema.js.map

package/dist/core/site-guide/types.d.ts

@@ -0,0 +1,83 @@
+/** Read-only learning contracts. Hosts supply facts; plugins supply prose, never read effects. */
+export interface GuideCaller {
+    readonly principalId: string;
+}
+export interface GuidePointer {
+    readonly label: string;
+    readonly tool?: string | undefined;
+    readonly href?: string | undefined;
+    readonly permissions: readonly string[];
+}
+export interface GuideWorkflow {
+    readonly title: string;
+    readonly steps: readonly string[];
+    readonly permissions: readonly string[];
+}
+export interface GuideTopic {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly explanation: string;
+    readonly permissions: readonly string[];
+    readonly pointers: readonly GuidePointer[];
+    readonly workflows: readonly GuideWorkflow[];
+}
+export interface GuideContribution {
+    readonly pluginId: string;
+    readonly topics: readonly GuideTopic[];
+}
+export interface GuideContributionResult {
+    readonly items: readonly GuideContribution[];
+    /** Host-local diagnostics; never expose arbitrary loader messages to the model. */
+    readonly refusals: readonly string[];
+}
+export type GuideFact = {
+    readonly status: 'ok';
+    readonly data: unknown;
+    readonly truncated?: boolean;
+} | {
+    readonly status: 'forbidden' | 'unavailable';
+};
+/** Only a permission-scoped, explicitly projected DTO may leave the host adapter. */
+export interface SiteFactsPort {
+    read(input: {
+        readonly caller: GuideCaller;
+        readonly topics: readonly string[];
+    }, options?: Record<string, never>): Promise<Readonly<Record<string, GuideFact>>>;
+}
+export interface SiteGuidePorts {
+    readonly facts: SiteFactsPort;
+    readonly authorize: (input: {
+        readonly caller: GuideCaller;
+        readonly permission: string;
+    }, options?: Record<string, never>) => Promise<boolean>;
+    readonly loadContributions?: (input: {
+        readonly caller: GuideCaller;
+    }, options?: Record<string, never>) => Promise<GuideContributionResult>;
+    readonly builtInTopics?: readonly GuideTopic[];
+}
+export interface GuideTopicView {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly explanation?: string;
+    readonly pointers?: readonly Omit<GuidePointer, 'permissions'>[];
+    readonly workflows?: readonly Omit<GuideWorkflow, 'permissions'>[];
+    readonly source: string;
+}
+export interface GuideResult {
+    readonly operation: 'overview' | 'explain';
+    readonly topics: readonly GuideTopicView[];
+    readonly facts: Readonly<Record<string, GuideFact>>;
+    /** Granted permissions consulted for this result, rather than an inventory of the caller's roles. */
+    readonly callerPermissions: readonly string[];
+    readonly enrichment: 'ok' | 'unavailable' | 'partial';
+}
+export interface SiteGuide {
+    run(input: {
+        readonly caller: GuideCaller;
+        readonly operation: 'overview' | 'explain';
+        readonly topic?: string;
+    }, options?: Record<string, never>): Promise<GuideResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/site-guide/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/skills/install/archive.js

@@ -3,45 +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({});
         }
     }
     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/index.d.ts

@@ -8,4 +8,5 @@ export * from "./layout.js";
 export * from "./live-registration.js";
 export * from "./fetch-adapter.js";
 export * from "./node-filesystem.js";
+export * from "./yauzl-archive-reader.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/skills/install/index.js

@@ -8,4 +8,5 @@ export * from "./layout.js";
 export * from "./live-registration.js";
 export * from "./fetch-adapter.js";
 export * from "./node-filesystem.js";
+export * from "./yauzl-archive-reader.js";
 //# sourceMappingURL=index.js.map