@jini-ai/agent-plugins 0.4.0

package/dist/lifecycle/bundled-digests.d.ts

@@ -0,0 +1,27 @@
+import type { AgentPluginLifecyclePorts } from "./ports.js";
+export declare const BUNDLED_DIGESTS_FILENAME = "bundled-digests.json";
+export type BundledAgentPluginDigests = ReadonlyMap<string, string>;
+export interface SeededBundledAgentPluginDigest {
+    readonly pluginId: string;
+    readonly archiveDigest: string;
+}
+export interface InstalledDigestIdentity {
+    readonly pluginId: string;
+    readonly archiveDigest: string;
+}
+/** Internal composition; one state/queue instance per injected host context. */
+export declare function createBundledDigestsModule(ports: AgentPluginLifecyclePorts): {
+    readBundledAgentPluginDigests: (workspaceRoot: string) => Promise<BundledAgentPluginDigests>;
+    normalizeBundledDigests: (value: unknown) => BundledAgentPluginDigests;
+    recordBundledAgentPluginDigests: (required: {
+        readonly workspaceRoot: string;
+        readonly seeded: readonly SeededBundledAgentPluginDigest[];
+        readonly now?: ((required: Record<string, never>) => Date) | undefined;
+    }) => Promise<void>;
+    removeBundledAgentPluginDigest: (required: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+    }) => Promise<boolean>;
+    preferBundledAgentPluginDigests: <T extends InstalledDigestIdentity>(installed: readonly T[], bundled: BundledAgentPluginDigests) => readonly T[];
+};
+//# sourceMappingURL=bundled-digests.d.ts.map

package/dist/lifecycle/bundled-digests.js

@@ -0,0 +1,149 @@
+/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+import path from "node:path";
+export const BUNDLED_DIGESTS_FILENAME = "bundled-digests.json";
+function buildModule(ports) {
+    const open = ports.filesystem.open.bind(ports.filesystem);
+    const readFile = ports.filesystem.readFile.bind(ports.filesystem);
+    const rename = ports.filesystem.rename.bind(ports.filesystem);
+    const rm = ports.filesystem.rm.bind(ports.filesystem);
+    const randomUUID = () => ports.ids.newId();
+    const SHA256_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+    const SAFE_PLUGIN_ID_PATTERN = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+    const EMPTY_LEDGER = new Map();
+    async function readBundledAgentPluginDigests(workspaceRoot) {
+        let raw;
+        try {
+            raw = await readFile(path.join(workspaceRoot, BUNDLED_DIGESTS_FILENAME), "utf8");
+        }
+        catch {
+            return EMPTY_LEDGER;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return EMPTY_LEDGER;
+        }
+        return normalizeBundledDigests(parsed);
+    }
+    function normalizeBundledDigests(value) {
+        if (!isPlainObject(value) || value.schemaVersion !== 1 || !isPlainObject(value.plugins))
+            return EMPTY_LEDGER;
+        const digests = new Map();
+        for (const [pluginId, entry] of Object.entries(value.plugins)) {
+            if (!SAFE_PLUGIN_ID_PATTERN.test(pluginId))
+                continue;
+            if (!isPlainObject(entry))
+                continue;
+            const { archiveDigest } = entry;
+            if (typeof archiveDigest !== "string" || !SHA256_DIGEST_PATTERN.test(archiveDigest))
+                continue;
+            digests.set(pluginId, archiveDigest);
+        }
+        return digests;
+    }
+    async function recordBundledAgentPluginDigests(required) {
+        if (required.seeded.length === 0)
+            return;
+        const existing = await readBundledAgentPluginDigests(required.workspaceRoot);
+        const merged = new Map(existing);
+        const seededAt = (required.now?.({}) ?? new Date(ports.clock.nowMs())).toISOString();
+        for (const [pluginId, archiveDigest] of resolveThisBootsDigests(required.seeded)) {
+            if (archiveDigest === undefined)
+                merged.delete(pluginId);
+            else
+                merged.set(pluginId, archiveDigest);
+        }
+        const plugins = Object.fromEntries([...merged].map(([pluginId, archiveDigest]) => [pluginId, { archiveDigest, seededAt }]));
+        await writeLedgerAtomically(required.workspaceRoot, plugins);
+    }
+    function resolveThisBootsDigests(seeded) {
+        const thisBoot = new Map();
+        for (const { pluginId, archiveDigest } of seeded) {
+            if (!SAFE_PLUGIN_ID_PATTERN.test(pluginId) || !SHA256_DIGEST_PATTERN.test(archiveDigest))
+                continue;
+            if (thisBoot.has(pluginId) && thisBoot.get(pluginId) !== archiveDigest)
+                thisBoot.set(pluginId, undefined);
+            else
+                thisBoot.set(pluginId, archiveDigest);
+        }
+        return thisBoot;
+    }
+    async function removeBundledAgentPluginDigest(required) {
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(path.join(required.workspaceRoot, BUNDLED_DIGESTS_FILENAME), "utf8"));
+        }
+        catch {
+            return false;
+        }
+        if (!isPlainObject(parsed) || parsed.schemaVersion !== 1 || !isPlainObject(parsed.plugins))
+            return false;
+        if (!Object.hasOwn(parsed.plugins, required.pluginId))
+            return false;
+        const remaining = { ...parsed.plugins };
+        delete remaining[required.pluginId];
+        await writeLedgerAtomically(required.workspaceRoot, remaining);
+        return true;
+    }
+    async function writeLedgerAtomically(workspaceRoot, plugins) {
+        const finalPath = path.join(workspaceRoot, BUNDLED_DIGESTS_FILENAME);
+        const tempPath = `${finalPath}.tmp-${ports.process.pid}-${randomUUID()}`;
+        try {
+            const handle = await open(tempPath, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify({ schemaVersion: 1, plugins }, null, 2)}\n`, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(tempPath, finalPath);
+        }
+        catch (error) {
+            await rm(tempPath, { force: true });
+            throw error;
+        }
+    }
+    function preferBundledAgentPluginDigests(installed, bundled) {
+        if (bundled.size === 0)
+            return installed;
+        const supersededIds = idsNarrowableToTheirBundledDigest(installed, bundled);
+        if (supersededIds.size === 0)
+            return installed;
+        return installed.filter((plugin) => !supersededIds.has(plugin.pluginId) || plugin.archiveDigest === bundled.get(plugin.pluginId));
+    }
+    function idsNarrowableToTheirBundledDigest(installed, bundled) {
+        const digestsByPluginId = new Map();
+        for (const plugin of installed) {
+            const digests = digestsByPluginId.get(plugin.pluginId) ?? new Set();
+            digests.add(plugin.archiveDigest);
+            digestsByPluginId.set(plugin.pluginId, digests);
+        }
+        const narrowable = new Set();
+        for (const [pluginId, digests] of digestsByPluginId) {
+            if (digests.size < 2)
+                continue;
+            const bundledDigest = bundled.get(pluginId);
+            if (bundledDigest !== undefined && digests.has(bundledDigest))
+                narrowable.add(pluginId);
+        }
+        return narrowable;
+    }
+    function isPlainObject(value) {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+    return { readBundledAgentPluginDigests, normalizeBundledDigests, recordBundledAgentPluginDigests, removeBundledAgentPluginDigest, preferBundledAgentPluginDigests };
+}
+const instances = new WeakMap();
+/** Internal composition; one state/queue instance per injected host context. */
+export function createBundledDigestsModule(ports) {
+    let instance = instances.get(ports);
+    if (!instance) {
+        instance = buildModule(ports);
+        instances.set(ports, instance);
+    }
+    return instance;
+}
+//# sourceMappingURL=bundled-digests.js.map

package/dist/lifecycle/bundled-source-archive.d.ts

@@ -0,0 +1,13 @@
+import type { AgentPluginArchiveReaderPort } from "./install.js";
+import type { AgentPluginLifecyclePorts } from "./ports.js";
+export interface PackedAgentPluginArchive {
+    readonly bytes: Uint8Array;
+    readonly sha256: string;
+    readonly files: readonly string[];
+}
+/** Internal composition; one state/queue instance per injected host context. */
+export declare function createBundledSourceArchiveModule(ports: AgentPluginLifecyclePorts): {
+    packAgentPluginDirectory: (sourceDir: string) => Promise<PackedAgentPluginArchive>;
+    createBundledSourceArchiveReader: () => AgentPluginArchiveReaderPort;
+};
+//# sourceMappingURL=bundled-source-archive.d.ts.map

package/dist/lifecycle/bundled-source-archive.js

@@ -0,0 +1,96 @@
+/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+import { createHash } from "node:crypto";
+import path from "node:path";
+function buildModule(ports) {
+    const readdir = ports.filesystem.readdir.bind(ports.filesystem);
+    const readFile = ports.filesystem.readFile.bind(ports.filesystem);
+    const MAGIC = ports.bundledArchiveMagic;
+    const MAX_SOURCE_FILES = 2048;
+    async function packAgentPluginDirectory(sourceDir) {
+        const relativePaths = (await listRegularFiles(sourceDir, "")).sort();
+        if (relativePaths.length > MAX_SOURCE_FILES) {
+            throw new Error(`bundled agent plugin at '${sourceDir}' has ${relativePaths.length} files, over the ${MAX_SOURCE_FILES}-file cap — is this the right directory?`);
+        }
+        const chunks = [Buffer.from(MAGIC, "utf8")];
+        for (const relativePath of relativePaths) {
+            const content = await readFile(path.join(sourceDir, relativePath));
+            const pathBytes = Buffer.from(relativePath, "utf8");
+            chunks.push(Buffer.from(`F ${pathBytes.byteLength} ${content.byteLength}\n`, "utf8"), pathBytes, content);
+        }
+        const bytes = Buffer.concat(chunks);
+        return {
+            bytes: new Uint8Array(bytes),
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            files: relativePaths,
+        };
+    }
+    function createBundledSourceArchiveReader() {
+        return {
+            entries({ archive }) {
+                return readEntries(archive);
+            },
+        };
+    }
+    async function* readEntries(archive) {
+        const buffer = Buffer.from(archive.buffer, archive.byteOffset, archive.byteLength);
+        const magic = Buffer.from(MAGIC, "utf8");
+        if (buffer.byteLength < magic.byteLength || !buffer.subarray(0, magic.byteLength).equals(magic)) {
+            throw new Error("bundled agent plugin archive: bad magic — this reader only understands the configured bundled archive format");
+        }
+        let offset = magic.byteLength;
+        while (offset < buffer.byteLength) {
+            const newlineIndex = buffer.indexOf(0x0a, offset);
+            if (newlineIndex === -1)
+                throw new Error("bundled agent plugin archive: truncated entry header");
+            const header = buffer.subarray(offset, newlineIndex).toString("utf8");
+            const match = /^F (\d+) (\d+)$/.exec(header);
+            if (!match)
+                throw new Error(`bundled agent plugin archive: malformed entry header '${header}'`);
+            const pathLength = Number(match[1]);
+            const contentLength = Number(match[2]);
+            const pathStart = newlineIndex + 1;
+            const contentStart = pathStart + pathLength;
+            const contentEnd = contentStart + contentLength;
+            if (contentEnd > buffer.byteLength)
+                throw new Error("bundled agent plugin archive: truncated entry body");
+            const entryPath = buffer.subarray(pathStart, contentStart).toString("utf8");
+            const content = buffer.subarray(contentStart, contentEnd);
+            yield {
+                kind: "file",
+                entryPath,
+                declaredSize: contentLength,
+                openReadStream: () => onceAsyncIterable(new Uint8Array(content)),
+            };
+            offset = contentEnd;
+        }
+    }
+    async function* onceAsyncIterable(chunk) {
+        yield chunk;
+    }
+    async function listRegularFiles(dir, prefix) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                files.push(...(await listRegularFiles(path.join(dir, entry.name), relative)));
+            }
+            else if (entry.isFile()) {
+                files.push(relative);
+            }
+        }
+        return files;
+    }
+    return { packAgentPluginDirectory, createBundledSourceArchiveReader };
+}
+const instances = new WeakMap();
+/** Internal composition; one state/queue instance per injected host context. */
+export function createBundledSourceArchiveModule(ports) {
+    let instance = instances.get(ports);
+    if (!instance) {
+        instance = buildModule(ports);
+        instances.set(ports, instance);
+    }
+    return instance;
+}
+//# sourceMappingURL=bundled-source-archive.js.map

package/dist/lifecycle/capability-projection.d.ts

@@ -0,0 +1,11 @@
+/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+import type { McpServerConfig } from "./manifest.js";
+import type { AgentPluginLifecyclePorts } from "./ports.js";
+/** Internal composition; one state/queue instance per injected host context. */
+export declare function createCapabilityProjectionModule(ports: AgentPluginLifecyclePorts): {
+    classifyAgentPluginMcpServerTrust: (server: Pick<McpServerConfig, "type">) => "auto-admit" | "requires-confirmation";
+    readInstalledSkillMarkdown: (packageRoot: string, skillPath: string) => Promise<string>;
+    readInstalledMcpServerIds: (packageRoot: string) => Promise<readonly string[]>;
+    readInstalledMcpServers: (packageRoot: string) => Promise<Readonly<Record<string, McpServerConfig>>>;
+};
+//# sourceMappingURL=capability-projection.d.ts.map

package/dist/lifecycle/capability-projection.js

@@ -0,0 +1,60 @@
+import { parseAgentPluginMcpConfig as parseAgentPluginMcpConfigValue } from "./manifest.js";
+import { createPackagePathsModule } from "./package-paths.js";
+function buildModule(ports) {
+    const readFile = ports.filesystem.readFile.bind(ports.filesystem);
+    const parseAgentPluginMcpConfig = (value, pluginManifest) => parseAgentPluginMcpConfigValue({ value, extensionNamespace: ports.extensionNamespace }, { pluginManifest, readServerMetadata: ports.readServerMetadata });
+    const { assertContainedOnDisk } = createPackagePathsModule(ports);
+    function classifyAgentPluginMcpServerTrust(server) {
+        return server.type === "stdio" ? "requires-confirmation" : "auto-admit";
+    }
+    async function readInstalledSkillMarkdown(packageRoot, skillPath) {
+        const absolute = await assertContainedOnDisk(packageRoot, skillPath);
+        return readFile(absolute, "utf8");
+    }
+    async function readInstalledMcpConfig(packageRoot) {
+        let raw;
+        try {
+            const absolute = await assertContainedOnDisk(packageRoot, "mcp.json");
+            raw = await readFile(absolute, "utf8");
+        }
+        catch {
+            return null;
+        }
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        let manifest;
+        try {
+            const absolute = await assertContainedOnDisk(packageRoot, "plugin.json");
+            manifest = JSON.parse(await readFile(absolute, "utf8"));
+        }
+        catch {
+        }
+        const result = parseAgentPluginMcpConfig(parsedJson, manifest);
+        return result.ok ? result.config : null;
+    }
+    async function readInstalledMcpServerIds(packageRoot) {
+        const config = await readInstalledMcpConfig(packageRoot);
+        return config?.serverIds ?? [];
+    }
+    async function readInstalledMcpServers(packageRoot) {
+        const config = await readInstalledMcpConfig(packageRoot);
+        return config?.servers ?? {};
+    }
+    return { classifyAgentPluginMcpServerTrust, readInstalledSkillMarkdown, readInstalledMcpServerIds, readInstalledMcpServers };
+}
+const instances = new WeakMap();
+/** Internal composition; one state/queue instance per injected host context. */
+export function createCapabilityProjectionModule(ports) {
+    let instance = instances.get(ports);
+    if (!instance) {
+        instance = buildModule(ports);
+        instances.set(ports, instance);
+    }
+    return instance;
+}
+//# sourceMappingURL=capability-projection.js.map

package/dist/lifecycle/fetch-archive.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Historical lifecycle rationale, carried with the implementation during consumer adoption.
+ * @file The missing front half of the Agent Plugin install pipeline: URL -> verified bytes.
+ *
+ * `install.ts` deliberately takes `archive: Uint8Array` and never a URL — it is a pure
+ * verify/extract/publish step with no network surface at all. This module is the one place that
+ * talks to the network, and it hands `install.ts` exactly what it already accepts. The split is
+ * kept on purpose: every hostile-archive guard in `install.ts` (`DIGEST_MISMATCH`, zip-slip,
+ * decompression caps) stays reachable from a plain in-memory buffer in tests, with no fetch mock.
+ *
+ * What this module does NOT do:
+ * - It does not decide whether a digest is trustworthy. `expectedSha256` is verified by
+ *   `install.ts`, not here; {@link fetchAgentPluginArchive} only reports the digest of what
+ *   actually arrived so a caller can pin it.
+ * - It does not follow a redirect chain by hand. `fetch` handles redirects; the scheme guard below
+ *   re-runs on the FINAL response URL so an `https://` start cannot be redirected onto a
+ *   non-network scheme.
+ * - It does not trust `Content-Length`. That header is attacker-controlled for a hostile host; the
+ *   cap below is enforced against bytes actually read, and `Content-Length` is used only as an
+ *   early reject so an obviously-oversized download is not started at all.
+ */
+import type { AgentPluginOutboundGuardPort, AgentPluginFetchPort } from "./ports.js";
+export type AgentPluginFetchErrorCode = "UNSUPPORTED_URL" | "REQUEST_FAILED" | "HTTP_ERROR" | "ARCHIVE_TOO_LARGE" | "EMPTY_BODY";
+/**
+ * The URL did not parse, or its scheme is not in {@link ALLOWED_PROTOCOLS}.
+ *
+ * The request never produced a response — DNS failure, connection refused, TLS failure, abort.
+ *
+ * A response arrived with a non-2xx status.
+ *
+ * The response body exceeded {@link MAX_ARCHIVE_BYTES}, by header or by bytes actually read.
+ *
+ * A 2xx response with no body at all — never a valid archive, and a clearer error than letting
+ * the zip reader fail on zero bytes.
+ */
+export declare class AgentPluginFetchError extends Error {
+    readonly code: AgentPluginFetchErrorCode;
+    constructor({ code, message }: {
+        readonly code: AgentPluginFetchErrorCode;
+        readonly message: string;
+    }, options?: {
+        cause?: unknown;
+    });
+}
+export interface FetchAgentPluginArchiveRequired {
+    readonly url: string;
+    readonly fetch: AgentPluginFetchPort;
+    readonly outboundGuard: AgentPluginOutboundGuardPort;
+}
+/**
+ * Absolute `https:` or `http:` URL of a plugin `.zip`.
+ */
+export interface FetchAgentPluginArchiveOptional {
+    readonly maxBytes?: (number) | undefined;
+    readonly signal?: (AbortSignal) | undefined;
+}
+/**
+ * Injectable for tests and for a caller that needs its own agent/proxy. Defaults to global `fetch`.
+ *
+ * Lowered by a caller that wants a tighter cap than the module default. Never raised above
+ * {@link MAX_ARCHIVE_BYTES} — a larger value is clamped, because `install.ts` would reject it anyway.
+ *
+ * Forwarded to `fetch`, so a caller can time out or cancel a slow download.
+ */
+export interface FetchedAgentPluginArchive {
+    readonly archive: Uint8Array;
+    readonly sha256: string;
+    readonly resolvedUrl: string;
+}
+/**
+ * Lowercase hex SHA-256 of `archive` as received. Pass to `installAgentPlugin` as
+ * `expectedSha256` only if the caller has independently decided to trust these bytes — this value
+ * is computed from the download itself and therefore proves nothing about origin on its own.
+ *
+ * The FINAL URL after redirects, which may differ from the requested one.
+ *
+ * Downloads one Agent Plugin archive into memory, bounded and digested.
+ *
+ * @throws {AgentPluginFetchError} For every expected failure. A caller distinguishes them by `code`.
+ * @complexity O(b) in bytes downloaded, bounded by `maxBytes`.
+ */
+export declare function fetchAgentPluginArchive(required: FetchAgentPluginArchiveRequired, optional?: FetchAgentPluginArchiveOptional): Promise<FetchedAgentPluginArchive>;
+/**
+ * The module's own cap, exported so a caller (or a test pinning it against `install.ts`'s
+ * `LIMITS.maxArchiveBytes`) can read it without duplicating the number.
+ */
+export declare function maxAgentPluginArchiveBytes(_required: Record<string, never>): number;
+//# sourceMappingURL=fetch-archive.d.ts.map

package/dist/lifecycle/fetch-archive.js

@@ -0,0 +1,215 @@
+import { createHash } from "node:crypto";
+import { STATUS_CODES } from "node:http";
+/**
+ * Mirrors `install.ts`'s own `LIMITS.maxArchiveBytes` — a download this module would accept but
+ * `installAgentPlugin` would then reject with `ARCHIVE_TOO_LARGE` is wasted bandwidth, so the cap
+ * is enforced at the earliest point it can be. Kept as its own constant rather than imported so
+ * this module has no dependency on `install.ts`; the pairing is asserted by a unit test instead.
+ */
+const MAX_ARCHIVE_BYTES = 32 * 1024 * 1024;
+/**
+ * `http:` is permitted alongside `https:` because a self-hosted the host's first registry is realistically
+ * a machine on its own network (and because the local end-to-end proof of this pipeline serves over
+ * loopback). Transport confidentiality is NOT what protects an install here — `expectedSha256` is.
+ * Every other scheme is refused: `file:`/`data:` would turn a "download a plugin" call into an
+ * arbitrary local-file read reachable from whatever supplies the URL.
+ */
+const ALLOWED_PROTOCOLS = new Set(["https:", "http:"]);
+/**
+ * The URL did not parse, or its scheme is not in {@link ALLOWED_PROTOCOLS}.
+ *
+ * The request never produced a response — DNS failure, connection refused, TLS failure, abort.
+ *
+ * A response arrived with a non-2xx status.
+ *
+ * The response body exceeded {@link MAX_ARCHIVE_BYTES}, by header or by bytes actually read.
+ *
+ * A 2xx response with no body at all — never a valid archive, and a clearer error than letting
+ * the zip reader fail on zero bytes.
+ */
+export class AgentPluginFetchError extends Error {
+    code;
+    constructor({ code, message }, options = {}) {
+        super(message, options);
+        this.name = "AgentPluginFetchError";
+        this.code = code;
+    }
+}
+/**
+ * Lowercase hex SHA-256 of `archive` as received. Pass to `installAgentPlugin` as
+ * `expectedSha256` only if the caller has independently decided to trust these bytes — this value
+ * is computed from the download itself and therefore proves nothing about origin on its own.
+ *
+ * The FINAL URL after redirects, which may differ from the requested one.
+ *
+ * Downloads one Agent Plugin archive into memory, bounded and digested.
+ *
+ * @throws {AgentPluginFetchError} For every expected failure. A caller distinguishes them by `code`.
+ * @complexity O(b) in bytes downloaded, bounded by `maxBytes`.
+ */
+export async function fetchAgentPluginArchive(required, optional = {}) {
+    /**
+     * Re-checked against the FINAL url: `redirect: "follow"` means the scheme validated above is not
+     * necessarily the scheme the bytes came from.
+     */
+    const maxBytes = Math.min(optional.maxBytes ?? MAX_ARCHIVE_BYTES, MAX_ARCHIVE_BYTES);
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+        throw new RangeError("maxBytes must be a positive integer");
+    assertAllowedUrl(required.url, "requested");
+    const diagnosticUrl = redactArchiveUrl({ value: required.url });
+    let response;
+    let finalRequestedUrl = required.url;
+    try {
+        const downloaded = await fetchWithGuard(required, optional);
+        response = downloaded.response;
+        finalRequestedUrl = downloaded.resolvedUrl;
+    }
+    catch {
+        // Dependency messages and nested causes can contain signed redirect URLs or bare tokens.
+        // Keep neither: sanitizing only the requested URL still exposes secrets through error.cause.
+        throw new AgentPluginFetchError({ code: "REQUEST_FAILED", message: `could not fetch '${diagnosticUrl}': archive request failed` }, {
+            cause: new Error("archive request failed"),
+        });
+    }
+    // A server-controlled reason phrase can reflect secrets; use the standard status label.
+    if (!response.ok) {
+        throw new AgentPluginFetchError({ code: "HTTP_ERROR", message: `'${diagnosticUrl}' returned HTTP ${response.status} ${STATUS_CODES[response.status] ?? ''}`.trimEnd() });
+    }
+    const resolvedUrl = response.url || finalRequestedUrl;
+    assertAllowedUrl(resolvedUrl, "redirected-to");
+    assertDeclaredSizeWithinCap(response, maxBytes, diagnosticUrl);
+    let archive;
+    try {
+        archive = await readBodyWithinCap(response, maxBytes, diagnosticUrl);
+    }
+    catch (error) {
+        // Preserve our bounded-download error; stream failures must not escape as raw transport text.
+        if (error instanceof AgentPluginFetchError && error.code === "ARCHIVE_TOO_LARGE") {
+            throw new AgentPluginFetchError({ code: "ARCHIVE_TOO_LARGE", message: `'${diagnosticUrl}' body exceeded the ${maxBytes}-byte cap` });
+        }
+        throw new AgentPluginFetchError({ code: "REQUEST_FAILED", message: `could not read '${diagnosticUrl}': archive response body failed` }, {
+            cause: new Error("archive response body failed"),
+        });
+    }
+    if (archive.byteLength === 0) {
+        throw new AgentPluginFetchError({ code: "EMPTY_BODY", message: `'${diagnosticUrl}' returned an empty body` });
+    }
+    return {
+        archive,
+        sha256: createHash("sha256").update(archive).digest("hex"),
+        resolvedUrl,
+    };
+}
+/**
+ * The module's own cap, exported so a caller (or a test pinning it against `install.ts`'s
+ * `LIMITS.maxArchiveBytes`) can read it without duplicating the number.
+ */
+export function maxAgentPluginArchiveBytes(_required) {
+    return MAX_ARCHIVE_BYTES;
+}
+function assertAllowedUrl(value, position) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new AgentPluginFetchError({ code: "UNSUPPORTED_URL", message: `'${redactArchiveUrl({ value })}' is not an absolute URL` });
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new AgentPluginFetchError({ code: "UNSUPPORTED_URL", message: `${position} URL '${redactArchiveUrl({ value })}' uses unsupported scheme '${parsed.protocol}' — only https: and http: are allowed` });
+    }
+}
+/**
+ * Early reject on a self-declared oversized body. Advisory only — {@link readBodyWithinCap} is the
+ * enforcement, because a hostile host can under-report or omit this header entirely.
+ */
+function assertDeclaredSizeWithinCap(response, maxBytes, url) {
+    const header = response.headers.get("content-length");
+    if (header === null)
+        return;
+    const declared = Number(header);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw new AgentPluginFetchError({ code: "ARCHIVE_TOO_LARGE", message: `'${url}' declares ${declared} bytes, over the ${maxBytes}-byte cap` });
+    }
+}
+/**
+ * Reads the body chunk by chunk, aborting the moment the running total would exceed the cap — so a
+ * hostile endpoint streaming an unbounded body cannot drive this process out of memory. Buffering
+ * the whole response first (`await response.arrayBuffer()`) would defeat the cap entirely.
+ */
+async function readBodyWithinCap(response, maxBytes, url) {
+    if (response.body === null)
+        return new Uint8Array(0);
+    const chunks = [];
+    let total = 0;
+    /**
+     * Releases the connection on the throw path too; without it an aborted oversized download
+     * leaves the socket held until GC.
+     */
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value === undefined)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                throw new AgentPluginFetchError({ code: "ARCHIVE_TOO_LARGE", message: `'${url}' body exceeded the ${maxBytes}-byte cap` });
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const archive = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        archive.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return archive;
+}
+/**
+ * Diagnostics retain only the URL's public location; requests and resolvedUrl retain the original.
+ * Unparseable input is never echoed because its credential boundary cannot be identified safely.
+ * @complexity O(n) time and space in the URL length.
+ */
+function redactArchiveUrl({ value }) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return "[invalid URL]";
+    }
+    if (!parsed.username && !parsed.password && !parsed.search && !parsed.hash)
+        return value;
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.href;
+}
+/** Redirects are followed only after guarding each destination; never contact an unguarded hop. */
+async function fetchWithGuard(required, optional) {
+    let url = required.url;
+    for (let hop = 0; hop <= 10; hop++) {
+        assertAllowedUrl(url, 'requested');
+        await required.outboundGuard.assertAllowed({ url });
+        const response = await required.fetch({ url }, {
+            redirect: 'manual', ...(optional.signal ? { signal: optional.signal } : {}),
+        });
+        if (![301, 302, 303, 307, 308].includes(response.status))
+            return { response, resolvedUrl: url };
+        const location = response.headers.get('location');
+        await response.body?.cancel();
+        if (!location)
+            throw new Error('Archive redirect has no Location header');
+        url = new URL(location, url).href;
+    }
+    throw new Error('Archive redirect limit exceeded');
+}
+//# sourceMappingURL=fetch-archive.js.map