@ai-agent-forge/agent-forge 0.85.0

package/dist/plugins/ecosystem/node-disk-registry-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-disk-registry-source.d.ts","sourceRoot":"","sources":["../../../src/plugins/ecosystem/node-disk-registry-source.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAoC,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAG9F,QAAA,MAAM,oCAAoC,GAAa,CAAC;AACxD,oEAAoE;AACpE,eAAO,MAAM,qCAAqC,QAAc,CAAC;AACjE,+EAA+E;AAC/E,eAAO,MAAM,wCAAwC,QAAY,CAAC;AAClE,6FAA6F;AAC7F,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAOrD,MAAM,MAAM,iCAAiC,GAC1C,WAAW,GACX,uBAAuB,GACvB,eAAe,GACf,kBAAkB,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,WAAW,CAAC;AAEf;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IAEjD,YAAY,IAAI,EAAE,iCAAiC,EAAE,OAAO,EAAE,MAAM,EAInE;CACD;AAED,MAAM,WAAW,+BAA+B;IAC/C,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oCAAoC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,oCAAoC,CAAC;IAC9D;;;;;;OAMG;IACH,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CACxC,KAAK,EAAE,oCAAoC,KACvC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACjC;AA6JD;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CACnD,OAAO,EAAE,+BAA+B,GACtC,wBAAwB,CAkD1B","sourcesContent":["import { open } from \"node:fs/promises\";\nimport { isAbsolute, join, relative } from \"node:path\";\nimport type { PluginRegistryManifestEnvelopeV1, PluginRegistrySourceV1 } from \"./registry.ts\";\nimport type { PluginManifestV1 } from \"./types.ts\";\n\nconst NODE_DISK_REGISTRY_SOURCE_VERSION_V1 = 1 as const;\n/** Maximum index.v1.json bytes accepted by this source boundary. */\nexport const MAX_NODE_DISK_REGISTRY_INDEX_BYTES_V1 = 1024 * 1024;\n/** Maximum per-installation agent-forge.json bytes accepted by this source. */\nexport const MAX_NODE_DISK_REGISTRY_MANIFEST_BYTES_V1 = 64 * 1024;\n/** Maximum index records projected by one list() call; matches the registry manifest cap. */\nexport const MAX_NODE_DISK_REGISTRY_RECORDS_V1 = 256;\n\nconst INDEX_FILE_V1 = \"index.v1.json\";\nconst ECOSYSTEM_MANIFEST_FILE_V1 = \"agent-forge.json\";\nconst CAPABILITY_MANIFEST_FILE_V1 = \"plugin.json\";\nconst NODE_PACKAGE_FORMAT_VERSION_V1 = 1;\n\nexport type NodeDiskRegistrySourceErrorCodeV1 =\n\t| \"cancelled\"\n\t| \"invalid_configuration\"\n\t| \"invalid_index\"\n\t| \"invalid_manifest\"\n\t| \"identity_mismatch\"\n\t| \"too_many_records\"\n\t| \"io_failed\";\n\n/**\n * Deliberately does not retain filesystem exceptions or file contents: callers\n * must not turn registry diagnostics into a path or package disclosure.\n */\nexport class NodeDiskRegistrySourceErrorV1 extends Error {\n\treadonly code: NodeDiskRegistrySourceErrorCodeV1;\n\n\tconstructor(code: NodeDiskRegistrySourceErrorCodeV1, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"NodeDiskRegistrySourceErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\nexport interface NodeDiskRegistrySourceOptionsV1 {\n\t/** Absolute host-owned default install store directory. It is never returned in a DTO. */\n\treadonly rootDirectory: string;\n}\n\nexport interface NodeDiskRegistrySourceResolveInputV1 {\n\treadonly pluginId: string;\n\treadonly pluginVersion: string;\n\treadonly signal?: AbortSignal;\n}\n\nexport interface NodeDiskRegistrySourceV1 extends PluginRegistrySourceV1 {\n\treadonly version: typeof NODE_DISK_REGISTRY_SOURCE_VERSION_V1;\n\t/**\n\t * Internal host channel (D-075 S2): absolute `plugin.json` path of the\n\t * installation directory matching `{pluginId, pluginVersion}` in the store\n\t * index, for the sdk's installed-plugin code loading. Registry snapshots\n\t * still carry no paths; undefined means no matching record or the manifest\n\t * file is absent from the installation directory.\n\t */\n\treadonly resolveCapabilityManifestPath?: (\n\t\tinput: NodeDiskRegistrySourceResolveInputV1,\n\t) => Promise<string | undefined>;\n}\n\ninterface DiskIndexRecordV1 {\n\treadonly installationRef: string;\n\treadonly directory: string;\n\treadonly pluginId: string;\n\treadonly pluginVersion: string;\n\treadonly manifestDigest: string;\n\treadonly scope: \"global\" | \"project\";\n\treadonly scopeRef: string;\n\treadonly state: \"installed\" | \"active\" | \"retained\";\n}\n\nconst INDEX_KEYS_V1 = [\n\t\"installationRef\",\n\t\"directory\",\n\t\"pluginId\",\n\t\"pluginVersion\",\n\t\"manifestDigest\",\n\t\"scope\",\n\t\"scopeRef\",\n\t\"state\",\n] as const;\n\nfunction opaqueField(value: unknown, max: number): value is string {\n\treturn (\n\t\ttypeof value === \"string\" &&\n\t\tvalue.length > 0 &&\n\t\tvalue.length <= max &&\n\t\t!/[\\u0000-\\u001f\\u007f]/u.test(value) &&\n\t\t!/\\s/u.test(value) &&\n\t\t!/^(?:file:|[a-z]:[\\\\/]|[\\\\/]{1,2}|\\\\\\\\)/iu.test(value)\n\t);\n}\n\nfunction boundedField(value: unknown, max: number): value is string {\n\treturn typeof value === \"string\" && value.length > 0 && value.length <= max && !/[\\u0000-\\u001f\\u007f]/u.test(value);\n}\n\nfunction withinRoot(root: string, value: string): boolean {\n\tif (!isAbsolute(value)) return false;\n\tconst relativePath = relative(root, value);\n\treturn relativePath !== \"\" && !relativePath.startsWith(\"..\") && !isAbsolute(relativePath);\n}\n\nfunction validateRecord(root: string, value: unknown, index: number): DiskIndexRecordV1 {\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", `Index record ${index} is not an object`);\n\tconst record = value as Record<string, unknown>;\n\tconst keys = INDEX_KEYS_V1;\n\tif (Object.keys(record).length !== keys.length || keys.some((key) => !(key in record)))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", `Index record ${index} has an invalid schema`);\n\tif (\n\t\t!opaqueField(record.installationRef, 2048) ||\n\t\t!boundedField(record.directory, 2048) ||\n\t\t!boundedField(record.pluginId, 256) ||\n\t\t!boundedField(record.pluginVersion, 256) ||\n\t\t!boundedField(record.manifestDigest, 512) ||\n\t\t!opaqueField(record.scopeRef, 2048) ||\n\t\t(record.scope !== \"global\" && record.scope !== \"project\") ||\n\t\t(record.state !== \"installed\" && record.state !== \"active\" && record.state !== \"retained\") ||\n\t\t!withinRoot(root, record.directory)\n\t)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", `Index record ${index} is invalid`);\n\treturn {\n\t\tinstallationRef: record.installationRef,\n\t\tdirectory: record.directory,\n\t\tpluginId: record.pluginId,\n\t\tpluginVersion: record.pluginVersion,\n\t\tmanifestDigest: record.manifestDigest,\n\t\tscope: record.scope,\n\t\tscopeRef: record.scopeRef,\n\t\tstate: record.state,\n\t};\n}\n\nfunction parseIndex(root: string, raw: string): readonly DiskIndexRecordV1[] {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch {\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", \"Install store index JSON is invalid\");\n\t}\n\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", \"Install store index is not an object\");\n\tconst value = parsed as Record<string, unknown>;\n\tif (\n\t\tObject.keys(value).length !== 2 ||\n\t\tvalue.version !== NODE_DISK_REGISTRY_SOURCE_VERSION_V1 ||\n\t\t!Array.isArray(value.records)\n\t)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", \"Install store index schema is unsupported\");\n\tif (value.records.length > MAX_NODE_DISK_REGISTRY_RECORDS_V1)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"too_many_records\", \"Install store index exceeds the record limit\");\n\treturn value.records.map((record, index) => validateRecord(root, record, index));\n}\n\n/** Read a bounded UTF-8 file; the absolute path never appears in a thrown message. */\nasync function readBoundedFile(path: string, maxBytes: number, label: string): Promise<string> {\n\tconst handle = await open(path, \"r\");\n\ttry {\n\t\tconst stat = await handle.stat();\n\t\tif (!stat.isFile() || stat.size > maxBytes)\n\t\t\tthrow new NodeDiskRegistrySourceErrorV1(\n\t\t\t\tlabel === \"index\" ? \"invalid_index\" : \"invalid_manifest\",\n\t\t\t\t`${label} exceeds the size limit`,\n\t\t\t);\n\t\treturn await handle.readFile(\"utf8\");\n\t} finally {\n\t\tawait handle.close().catch(() => undefined);\n\t}\n}\n\nfunction parseManifest(record: DiskIndexRecordV1, raw: string): PluginManifestV1 {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch {\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_manifest\", \"Installed plugin manifest JSON is invalid\");\n\t}\n\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_manifest\", \"Installed plugin manifest is not an object\");\n\tconst value = { ...(parsed as Record<string, unknown>) };\n\tif (value.packageFormatVersion !== undefined && value.packageFormatVersion !== NODE_PACKAGE_FORMAT_VERSION_V1)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_manifest\", \"Installed plugin package format is unsupported\");\n\t// The package envelope version is an install-host field; it is not part of\n\t// PluginManifestV1 and the stable manifest digest excludes it.\n\tdelete value.packageFormatVersion;\n\tif (value.id !== record.pluginId || value.pluginVersion !== record.pluginVersion)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\n\t\t\t\"identity_mismatch\",\n\t\t\t`Installed plugin manifest identity does not match index record for ${record.pluginId}@${record.pluginVersion}`,\n\t\t);\n\treturn value as unknown as PluginManifestV1;\n}\n\n/** Read the install store index records; undefined when the store is empty. */\nasync function readIndexRecords(\n\trootDirectory: string,\n\tsignal: AbortSignal | undefined,\n): Promise<readonly DiskIndexRecordV1[] | undefined> {\n\tif (signal?.aborted) throw new NodeDiskRegistrySourceErrorV1(\"cancelled\", \"Disk registry source read was cancelled\");\n\tlet rawIndex: string;\n\ttry {\n\t\trawIndex = await readBoundedFile(\n\t\t\tjoin(rootDirectory, INDEX_FILE_V1),\n\t\t\tMAX_NODE_DISK_REGISTRY_INDEX_BYTES_V1,\n\t\t\t\"index\",\n\t\t);\n\t} catch (error) {\n\t\tif (error instanceof NodeDiskRegistrySourceErrorV1) throw error;\n\t\tif (error instanceof Error && \"code\" in error && error.code === \"ENOENT\") return undefined;\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"io_failed\", \"Install store index could not be read\");\n\t}\n\treturn parseIndex(rootDirectory, rawIndex);\n}\n\n/**\n * Read-only registry source over the default install store. It projects the\n * persistent index and each installation instance's ecosystem manifest as\n * bounded envelopes for the registry's own digest verification. It never\n * writes the index or installation directories, and installation directories\n * stay inside the host-owned store.\n */\nexport function createNodeDiskPluginRegistrySourceV1(\n\toptions: NodeDiskRegistrySourceOptionsV1,\n): NodeDiskRegistrySourceV1 {\n\tconst rootDirectory = options.rootDirectory;\n\tif (typeof rootDirectory !== \"string\" || !isAbsolute(rootDirectory) || rootDirectory.trim() === \"\")\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_configuration\", \"Install store root directory must be absolute\");\n\treturn {\n\t\tversion: NODE_DISK_REGISTRY_SOURCE_VERSION_V1,\n\t\tlist: async ({ signal } = {}) => {\n\t\t\tconst records = await readIndexRecords(rootDirectory, signal);\n\t\t\tif (records === undefined) return Object.freeze([]);\n\t\t\tconst envelopes: PluginRegistryManifestEnvelopeV1[] = [];\n\t\t\tfor (const record of records) {\n\t\t\t\tif (signal?.aborted)\n\t\t\t\t\tthrow new NodeDiskRegistrySourceErrorV1(\"cancelled\", \"Disk registry source read was cancelled\");\n\t\t\t\tlet rawManifest: string;\n\t\t\t\ttry {\n\t\t\t\t\trawManifest = await readBoundedFile(\n\t\t\t\t\t\tjoin(record.directory, ECOSYSTEM_MANIFEST_FILE_V1),\n\t\t\t\t\t\tMAX_NODE_DISK_REGISTRY_MANIFEST_BYTES_V1,\n\t\t\t\t\t\t\"manifest\",\n\t\t\t\t\t);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (error instanceof NodeDiskRegistrySourceErrorV1) throw error;\n\t\t\t\t\tthrow new NodeDiskRegistrySourceErrorV1(\"io_failed\", \"Installed plugin manifest could not be read\");\n\t\t\t\t}\n\t\t\t\tconst manifest = parseManifest(record, rawManifest);\n\t\t\t\tenvelopes.push({\n\t\t\t\t\tmanifest,\n\t\t\t\t\tsource: record.installationRef,\n\t\t\t\t\tmanifestDigest: record.manifestDigest,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn Object.freeze(envelopes);\n\t\t},\n\t\tresolveCapabilityManifestPath: async ({ pluginId, pluginVersion, signal }) => {\n\t\t\tconst records = await readIndexRecords(rootDirectory, signal);\n\t\t\tif (records === undefined) return undefined;\n\t\t\tconst record = records.find(\n\t\t\t\t(candidate) => candidate.pluginId === pluginId && candidate.pluginVersion === pluginVersion,\n\t\t\t);\n\t\t\tif (record === undefined) return undefined;\n\t\t\tconst manifestPath = join(record.directory, CAPABILITY_MANIFEST_FILE_V1);\n\t\t\ttry {\n\t\t\t\tconst handle = await open(manifestPath, \"r\");\n\t\t\t\tawait handle.close().catch(() => undefined);\n\t\t\t} catch {\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\treturn manifestPath;\n\t\t},\n\t};\n}\n"]}

package/dist/plugins/ecosystem/node-disk-registry-source.js

@@ -0,0 +1,208 @@
+import { open } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+const NODE_DISK_REGISTRY_SOURCE_VERSION_V1 = 1;
+/** Maximum index.v1.json bytes accepted by this source boundary. */
+export const MAX_NODE_DISK_REGISTRY_INDEX_BYTES_V1 = 1024 * 1024;
+/** Maximum per-installation agent-forge.json bytes accepted by this source. */
+export const MAX_NODE_DISK_REGISTRY_MANIFEST_BYTES_V1 = 64 * 1024;
+/** Maximum index records projected by one list() call; matches the registry manifest cap. */
+export const MAX_NODE_DISK_REGISTRY_RECORDS_V1 = 256;
+const INDEX_FILE_V1 = "index.v1.json";
+const ECOSYSTEM_MANIFEST_FILE_V1 = "agent-forge.json";
+const CAPABILITY_MANIFEST_FILE_V1 = "plugin.json";
+const NODE_PACKAGE_FORMAT_VERSION_V1 = 1;
+/**
+ * Deliberately does not retain filesystem exceptions or file contents: callers
+ * must not turn registry diagnostics into a path or package disclosure.
+ */
+export class NodeDiskRegistrySourceErrorV1 extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "NodeDiskRegistrySourceErrorV1";
+        this.code = code;
+    }
+}
+const INDEX_KEYS_V1 = [
+    "installationRef",
+    "directory",
+    "pluginId",
+    "pluginVersion",
+    "manifestDigest",
+    "scope",
+    "scopeRef",
+    "state",
+];
+function opaqueField(value, max) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= max &&
+        !/[\u0000-\u001f\u007f]/u.test(value) &&
+        !/\s/u.test(value) &&
+        !/^(?:file:|[a-z]:[\\/]|[\\/]{1,2}|\\\\)/iu.test(value));
+}
+function boundedField(value, max) {
+    return typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function withinRoot(root, value) {
+    if (!isAbsolute(value))
+        return false;
+    const relativePath = relative(root, value);
+    return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
+}
+function validateRecord(root, value, index) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new NodeDiskRegistrySourceErrorV1("invalid_index", `Index record ${index} is not an object`);
+    const record = value;
+    const keys = INDEX_KEYS_V1;
+    if (Object.keys(record).length !== keys.length || keys.some((key) => !(key in record)))
+        throw new NodeDiskRegistrySourceErrorV1("invalid_index", `Index record ${index} has an invalid schema`);
+    if (!opaqueField(record.installationRef, 2048) ||
+        !boundedField(record.directory, 2048) ||
+        !boundedField(record.pluginId, 256) ||
+        !boundedField(record.pluginVersion, 256) ||
+        !boundedField(record.manifestDigest, 512) ||
+        !opaqueField(record.scopeRef, 2048) ||
+        (record.scope !== "global" && record.scope !== "project") ||
+        (record.state !== "installed" && record.state !== "active" && record.state !== "retained") ||
+        !withinRoot(root, record.directory))
+        throw new NodeDiskRegistrySourceErrorV1("invalid_index", `Index record ${index} is invalid`);
+    return {
+        installationRef: record.installationRef,
+        directory: record.directory,
+        pluginId: record.pluginId,
+        pluginVersion: record.pluginVersion,
+        manifestDigest: record.manifestDigest,
+        scope: record.scope,
+        scopeRef: record.scopeRef,
+        state: record.state,
+    };
+}
+function parseIndex(root, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new NodeDiskRegistrySourceErrorV1("invalid_index", "Install store index JSON is invalid");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new NodeDiskRegistrySourceErrorV1("invalid_index", "Install store index is not an object");
+    const value = parsed;
+    if (Object.keys(value).length !== 2 ||
+        value.version !== NODE_DISK_REGISTRY_SOURCE_VERSION_V1 ||
+        !Array.isArray(value.records))
+        throw new NodeDiskRegistrySourceErrorV1("invalid_index", "Install store index schema is unsupported");
+    if (value.records.length > MAX_NODE_DISK_REGISTRY_RECORDS_V1)
+        throw new NodeDiskRegistrySourceErrorV1("too_many_records", "Install store index exceeds the record limit");
+    return value.records.map((record, index) => validateRecord(root, record, index));
+}
+/** Read a bounded UTF-8 file; the absolute path never appears in a thrown message. */
+async function readBoundedFile(path, maxBytes, label) {
+    const handle = await open(path, "r");
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > maxBytes)
+            throw new NodeDiskRegistrySourceErrorV1(label === "index" ? "invalid_index" : "invalid_manifest", `${label} exceeds the size limit`);
+        return await handle.readFile("utf8");
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+function parseManifest(record, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new NodeDiskRegistrySourceErrorV1("invalid_manifest", "Installed plugin manifest JSON is invalid");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new NodeDiskRegistrySourceErrorV1("invalid_manifest", "Installed plugin manifest is not an object");
+    const value = { ...parsed };
+    if (value.packageFormatVersion !== undefined && value.packageFormatVersion !== NODE_PACKAGE_FORMAT_VERSION_V1)
+        throw new NodeDiskRegistrySourceErrorV1("invalid_manifest", "Installed plugin package format is unsupported");
+    // The package envelope version is an install-host field; it is not part of
+    // PluginManifestV1 and the stable manifest digest excludes it.
+    delete value.packageFormatVersion;
+    if (value.id !== record.pluginId || value.pluginVersion !== record.pluginVersion)
+        throw new NodeDiskRegistrySourceErrorV1("identity_mismatch", `Installed plugin manifest identity does not match index record for ${record.pluginId}@${record.pluginVersion}`);
+    return value;
+}
+/** Read the install store index records; undefined when the store is empty. */
+async function readIndexRecords(rootDirectory, signal) {
+    if (signal?.aborted)
+        throw new NodeDiskRegistrySourceErrorV1("cancelled", "Disk registry source read was cancelled");
+    let rawIndex;
+    try {
+        rawIndex = await readBoundedFile(join(rootDirectory, INDEX_FILE_V1), MAX_NODE_DISK_REGISTRY_INDEX_BYTES_V1, "index");
+    }
+    catch (error) {
+        if (error instanceof NodeDiskRegistrySourceErrorV1)
+            throw error;
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw new NodeDiskRegistrySourceErrorV1("io_failed", "Install store index could not be read");
+    }
+    return parseIndex(rootDirectory, rawIndex);
+}
+/**
+ * Read-only registry source over the default install store. It projects the
+ * persistent index and each installation instance's ecosystem manifest as
+ * bounded envelopes for the registry's own digest verification. It never
+ * writes the index or installation directories, and installation directories
+ * stay inside the host-owned store.
+ */
+export function createNodeDiskPluginRegistrySourceV1(options) {
+    const rootDirectory = options.rootDirectory;
+    if (typeof rootDirectory !== "string" || !isAbsolute(rootDirectory) || rootDirectory.trim() === "")
+        throw new NodeDiskRegistrySourceErrorV1("invalid_configuration", "Install store root directory must be absolute");
+    return {
+        version: NODE_DISK_REGISTRY_SOURCE_VERSION_V1,
+        list: async ({ signal } = {}) => {
+            const records = await readIndexRecords(rootDirectory, signal);
+            if (records === undefined)
+                return Object.freeze([]);
+            const envelopes = [];
+            for (const record of records) {
+                if (signal?.aborted)
+                    throw new NodeDiskRegistrySourceErrorV1("cancelled", "Disk registry source read was cancelled");
+                let rawManifest;
+                try {
+                    rawManifest = await readBoundedFile(join(record.directory, ECOSYSTEM_MANIFEST_FILE_V1), MAX_NODE_DISK_REGISTRY_MANIFEST_BYTES_V1, "manifest");
+                }
+                catch (error) {
+                    if (error instanceof NodeDiskRegistrySourceErrorV1)
+                        throw error;
+                    throw new NodeDiskRegistrySourceErrorV1("io_failed", "Installed plugin manifest could not be read");
+                }
+                const manifest = parseManifest(record, rawManifest);
+                envelopes.push({
+                    manifest,
+                    source: record.installationRef,
+                    manifestDigest: record.manifestDigest,
+                });
+            }
+            return Object.freeze(envelopes);
+        },
+        resolveCapabilityManifestPath: async ({ pluginId, pluginVersion, signal }) => {
+            const records = await readIndexRecords(rootDirectory, signal);
+            if (records === undefined)
+                return undefined;
+            const record = records.find((candidate) => candidate.pluginId === pluginId && candidate.pluginVersion === pluginVersion);
+            if (record === undefined)
+                return undefined;
+            const manifestPath = join(record.directory, CAPABILITY_MANIFEST_FILE_V1);
+            try {
+                const handle = await open(manifestPath, "r");
+                await handle.close().catch(() => undefined);
+            }
+            catch {
+                return undefined;
+            }
+            return manifestPath;
+        },
+    };
+}
+//# sourceMappingURL=node-disk-registry-source.js.map

package/dist/plugins/ecosystem/node-disk-registry-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-disk-registry-source.js","sourceRoot":"","sources":["../../../src/plugins/ecosystem/node-disk-registry-source.ts"],"names":[],"mappings":"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","sourcesContent":["import { open } from \"node:fs/promises\";\nimport { isAbsolute, join, relative } from \"node:path\";\nimport type { PluginRegistryManifestEnvelopeV1, PluginRegistrySourceV1 } from \"./registry.ts\";\nimport type { PluginManifestV1 } from \"./types.ts\";\n\nconst NODE_DISK_REGISTRY_SOURCE_VERSION_V1 = 1 as const;\n/** Maximum index.v1.json bytes accepted by this source boundary. */\nexport const MAX_NODE_DISK_REGISTRY_INDEX_BYTES_V1 = 1024 * 1024;\n/** Maximum per-installation agent-forge.json bytes accepted by this source. */\nexport const MAX_NODE_DISK_REGISTRY_MANIFEST_BYTES_V1 = 64 * 1024;\n/** Maximum index records projected by one list() call; matches the registry manifest cap. */\nexport const MAX_NODE_DISK_REGISTRY_RECORDS_V1 = 256;\n\nconst INDEX_FILE_V1 = \"index.v1.json\";\nconst ECOSYSTEM_MANIFEST_FILE_V1 = \"agent-forge.json\";\nconst CAPABILITY_MANIFEST_FILE_V1 = \"plugin.json\";\nconst NODE_PACKAGE_FORMAT_VERSION_V1 = 1;\n\nexport type NodeDiskRegistrySourceErrorCodeV1 =\n\t| \"cancelled\"\n\t| \"invalid_configuration\"\n\t| \"invalid_index\"\n\t| \"invalid_manifest\"\n\t| \"identity_mismatch\"\n\t| \"too_many_records\"\n\t| \"io_failed\";\n\n/**\n * Deliberately does not retain filesystem exceptions or file contents: callers\n * must not turn registry diagnostics into a path or package disclosure.\n */\nexport class NodeDiskRegistrySourceErrorV1 extends Error {\n\treadonly code: NodeDiskRegistrySourceErrorCodeV1;\n\n\tconstructor(code: NodeDiskRegistrySourceErrorCodeV1, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"NodeDiskRegistrySourceErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\nexport interface NodeDiskRegistrySourceOptionsV1 {\n\t/** Absolute host-owned default install store directory. It is never returned in a DTO. */\n\treadonly rootDirectory: string;\n}\n\nexport interface NodeDiskRegistrySourceResolveInputV1 {\n\treadonly pluginId: string;\n\treadonly pluginVersion: string;\n\treadonly signal?: AbortSignal;\n}\n\nexport interface NodeDiskRegistrySourceV1 extends PluginRegistrySourceV1 {\n\treadonly version: typeof NODE_DISK_REGISTRY_SOURCE_VERSION_V1;\n\t/**\n\t * Internal host channel (D-075 S2): absolute `plugin.json` path of the\n\t * installation directory matching `{pluginId, pluginVersion}` in the store\n\t * index, for the sdk's installed-plugin code loading. Registry snapshots\n\t * still carry no paths; undefined means no matching record or the manifest\n\t * file is absent from the installation directory.\n\t */\n\treadonly resolveCapabilityManifestPath?: (\n\t\tinput: NodeDiskRegistrySourceResolveInputV1,\n\t) => Promise<string | undefined>;\n}\n\ninterface DiskIndexRecordV1 {\n\treadonly installationRef: string;\n\treadonly directory: string;\n\treadonly pluginId: string;\n\treadonly pluginVersion: string;\n\treadonly manifestDigest: string;\n\treadonly scope: \"global\" | \"project\";\n\treadonly scopeRef: string;\n\treadonly state: \"installed\" | \"active\" | \"retained\";\n}\n\nconst INDEX_KEYS_V1 = [\n\t\"installationRef\",\n\t\"directory\",\n\t\"pluginId\",\n\t\"pluginVersion\",\n\t\"manifestDigest\",\n\t\"scope\",\n\t\"scopeRef\",\n\t\"state\",\n] as const;\n\nfunction opaqueField(value: unknown, max: number): value is string {\n\treturn (\n\t\ttypeof value === \"string\" &&\n\t\tvalue.length > 0 &&\n\t\tvalue.length <= max &&\n\t\t!/[\\u0000-\\u001f\\u007f]/u.test(value) &&\n\t\t!/\\s/u.test(value) &&\n\t\t!/^(?:file:|[a-z]:[\\\\/]|[\\\\/]{1,2}|\\\\\\\\)/iu.test(value)\n\t);\n}\n\nfunction boundedField(value: unknown, max: number): value is string {\n\treturn typeof value === \"string\" && value.length > 0 && value.length <= max && !/[\\u0000-\\u001f\\u007f]/u.test(value);\n}\n\nfunction withinRoot(root: string, value: string): boolean {\n\tif (!isAbsolute(value)) return false;\n\tconst relativePath = relative(root, value);\n\treturn relativePath !== \"\" && !relativePath.startsWith(\"..\") && !isAbsolute(relativePath);\n}\n\nfunction validateRecord(root: string, value: unknown, index: number): DiskIndexRecordV1 {\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", `Index record ${index} is not an object`);\n\tconst record = value as Record<string, unknown>;\n\tconst keys = INDEX_KEYS_V1;\n\tif (Object.keys(record).length !== keys.length || keys.some((key) => !(key in record)))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", `Index record ${index} has an invalid schema`);\n\tif (\n\t\t!opaqueField(record.installationRef, 2048) ||\n\t\t!boundedField(record.directory, 2048) ||\n\t\t!boundedField(record.pluginId, 256) ||\n\t\t!boundedField(record.pluginVersion, 256) ||\n\t\t!boundedField(record.manifestDigest, 512) ||\n\t\t!opaqueField(record.scopeRef, 2048) ||\n\t\t(record.scope !== \"global\" && record.scope !== \"project\") ||\n\t\t(record.state !== \"installed\" && record.state !== \"active\" && record.state !== \"retained\") ||\n\t\t!withinRoot(root, record.directory)\n\t)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", `Index record ${index} is invalid`);\n\treturn {\n\t\tinstallationRef: record.installationRef,\n\t\tdirectory: record.directory,\n\t\tpluginId: record.pluginId,\n\t\tpluginVersion: record.pluginVersion,\n\t\tmanifestDigest: record.manifestDigest,\n\t\tscope: record.scope,\n\t\tscopeRef: record.scopeRef,\n\t\tstate: record.state,\n\t};\n}\n\nfunction parseIndex(root: string, raw: string): readonly DiskIndexRecordV1[] {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch {\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", \"Install store index JSON is invalid\");\n\t}\n\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", \"Install store index is not an object\");\n\tconst value = parsed as Record<string, unknown>;\n\tif (\n\t\tObject.keys(value).length !== 2 ||\n\t\tvalue.version !== NODE_DISK_REGISTRY_SOURCE_VERSION_V1 ||\n\t\t!Array.isArray(value.records)\n\t)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_index\", \"Install store index schema is unsupported\");\n\tif (value.records.length > MAX_NODE_DISK_REGISTRY_RECORDS_V1)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"too_many_records\", \"Install store index exceeds the record limit\");\n\treturn value.records.map((record, index) => validateRecord(root, record, index));\n}\n\n/** Read a bounded UTF-8 file; the absolute path never appears in a thrown message. */\nasync function readBoundedFile(path: string, maxBytes: number, label: string): Promise<string> {\n\tconst handle = await open(path, \"r\");\n\ttry {\n\t\tconst stat = await handle.stat();\n\t\tif (!stat.isFile() || stat.size > maxBytes)\n\t\t\tthrow new NodeDiskRegistrySourceErrorV1(\n\t\t\t\tlabel === \"index\" ? \"invalid_index\" : \"invalid_manifest\",\n\t\t\t\t`${label} exceeds the size limit`,\n\t\t\t);\n\t\treturn await handle.readFile(\"utf8\");\n\t} finally {\n\t\tawait handle.close().catch(() => undefined);\n\t}\n}\n\nfunction parseManifest(record: DiskIndexRecordV1, raw: string): PluginManifestV1 {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch {\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_manifest\", \"Installed plugin manifest JSON is invalid\");\n\t}\n\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed))\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_manifest\", \"Installed plugin manifest is not an object\");\n\tconst value = { ...(parsed as Record<string, unknown>) };\n\tif (value.packageFormatVersion !== undefined && value.packageFormatVersion !== NODE_PACKAGE_FORMAT_VERSION_V1)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_manifest\", \"Installed plugin package format is unsupported\");\n\t// The package envelope version is an install-host field; it is not part of\n\t// PluginManifestV1 and the stable manifest digest excludes it.\n\tdelete value.packageFormatVersion;\n\tif (value.id !== record.pluginId || value.pluginVersion !== record.pluginVersion)\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\n\t\t\t\"identity_mismatch\",\n\t\t\t`Installed plugin manifest identity does not match index record for ${record.pluginId}@${record.pluginVersion}`,\n\t\t);\n\treturn value as unknown as PluginManifestV1;\n}\n\n/** Read the install store index records; undefined when the store is empty. */\nasync function readIndexRecords(\n\trootDirectory: string,\n\tsignal: AbortSignal | undefined,\n): Promise<readonly DiskIndexRecordV1[] | undefined> {\n\tif (signal?.aborted) throw new NodeDiskRegistrySourceErrorV1(\"cancelled\", \"Disk registry source read was cancelled\");\n\tlet rawIndex: string;\n\ttry {\n\t\trawIndex = await readBoundedFile(\n\t\t\tjoin(rootDirectory, INDEX_FILE_V1),\n\t\t\tMAX_NODE_DISK_REGISTRY_INDEX_BYTES_V1,\n\t\t\t\"index\",\n\t\t);\n\t} catch (error) {\n\t\tif (error instanceof NodeDiskRegistrySourceErrorV1) throw error;\n\t\tif (error instanceof Error && \"code\" in error && error.code === \"ENOENT\") return undefined;\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"io_failed\", \"Install store index could not be read\");\n\t}\n\treturn parseIndex(rootDirectory, rawIndex);\n}\n\n/**\n * Read-only registry source over the default install store. It projects the\n * persistent index and each installation instance's ecosystem manifest as\n * bounded envelopes for the registry's own digest verification. It never\n * writes the index or installation directories, and installation directories\n * stay inside the host-owned store.\n */\nexport function createNodeDiskPluginRegistrySourceV1(\n\toptions: NodeDiskRegistrySourceOptionsV1,\n): NodeDiskRegistrySourceV1 {\n\tconst rootDirectory = options.rootDirectory;\n\tif (typeof rootDirectory !== \"string\" || !isAbsolute(rootDirectory) || rootDirectory.trim() === \"\")\n\t\tthrow new NodeDiskRegistrySourceErrorV1(\"invalid_configuration\", \"Install store root directory must be absolute\");\n\treturn {\n\t\tversion: NODE_DISK_REGISTRY_SOURCE_VERSION_V1,\n\t\tlist: async ({ signal } = {}) => {\n\t\t\tconst records = await readIndexRecords(rootDirectory, signal);\n\t\t\tif (records === undefined) return Object.freeze([]);\n\t\t\tconst envelopes: PluginRegistryManifestEnvelopeV1[] = [];\n\t\t\tfor (const record of records) {\n\t\t\t\tif (signal?.aborted)\n\t\t\t\t\tthrow new NodeDiskRegistrySourceErrorV1(\"cancelled\", \"Disk registry source read was cancelled\");\n\t\t\t\tlet rawManifest: string;\n\t\t\t\ttry {\n\t\t\t\t\trawManifest = await readBoundedFile(\n\t\t\t\t\t\tjoin(record.directory, ECOSYSTEM_MANIFEST_FILE_V1),\n\t\t\t\t\t\tMAX_NODE_DISK_REGISTRY_MANIFEST_BYTES_V1,\n\t\t\t\t\t\t\"manifest\",\n\t\t\t\t\t);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (error instanceof NodeDiskRegistrySourceErrorV1) throw error;\n\t\t\t\t\tthrow new NodeDiskRegistrySourceErrorV1(\"io_failed\", \"Installed plugin manifest could not be read\");\n\t\t\t\t}\n\t\t\t\tconst manifest = parseManifest(record, rawManifest);\n\t\t\t\tenvelopes.push({\n\t\t\t\t\tmanifest,\n\t\t\t\t\tsource: record.installationRef,\n\t\t\t\t\tmanifestDigest: record.manifestDigest,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn Object.freeze(envelopes);\n\t\t},\n\t\tresolveCapabilityManifestPath: async ({ pluginId, pluginVersion, signal }) => {\n\t\t\tconst records = await readIndexRecords(rootDirectory, signal);\n\t\t\tif (records === undefined) return undefined;\n\t\t\tconst record = records.find(\n\t\t\t\t(candidate) => candidate.pluginId === pluginId && candidate.pluginVersion === pluginVersion,\n\t\t\t);\n\t\t\tif (record === undefined) return undefined;\n\t\t\tconst manifestPath = join(record.directory, CAPABILITY_MANIFEST_FILE_V1);\n\t\t\ttry {\n\t\t\t\tconst handle = await open(manifestPath, \"r\");\n\t\t\t\tawait handle.close().catch(() => undefined);\n\t\t\t} catch {\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\treturn manifestPath;\n\t\t},\n\t};\n}\n"]}

package/dist/plugins/ecosystem/node-distribution-host.d.ts

@@ -0,0 +1,55 @@
+import type { PluginDistributionArtifactV1, PluginDistributionHostV1, PluginDistributionV1 } from "./distribution.ts";
+import { type NodePluginTrustRootOptionsV1 } from "./node-plugin-trust-root.ts";
+declare const NODE_DISTRIBUTION_HOST_VERSION_V1: 1;
+export interface NodeHttpPluginDistributionHostOptionsV1 {
+    /** Real `fetch` or a deterministic replacement for tests. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Exact `http(s)` origins. An empty allowlist is rejected. */
+    readonly allowedOrigins: readonly string[];
+    /** Optional host-owned directory. It is never returned as an artifact reference. */
+    readonly artifactDirectory?: string;
+    readonly requestTimeoutMs?: number;
+    readonly maxRedirects?: number;
+    readonly userAgent?: string;
+}
+export interface NodeHttpPluginDistributionHostV1 {
+    readonly version: typeof NODE_DISTRIBUTION_HOST_VERSION_V1;
+    readonly host: PluginDistributionHostV1;
+    /**
+     * Private Node-host reader for an installer that shares this host instance.
+     * It is not part of the model-facing distribution contract and never exposes
+     * a file path. The caller must consume it before releasing the artifact.
+     */
+    readonly openArtifact: (input: {
+        readonly artifact: PluginDistributionArtifactV1;
+        readonly signal?: AbortSignal;
+    }) => AsyncIterable<Uint8Array>;
+    /** Remove all artifacts owned by this host instance. */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Explicitly composed Node distribution stack. The caller supplies the trust
+ * root; no key or network origin is discovered implicitly.
+ */
+export interface NodeHttpPluginDistributionStackOptionsV1 extends NodeHttpPluginDistributionHostOptionsV1 {
+    readonly trustRoot: NodePluginTrustRootOptionsV1;
+    /** Shared clock for descriptor expiry and trust-key validity. */
+    readonly now?: () => number;
+}
+export interface NodeHttpPluginDistributionStackV1 extends NodeHttpPluginDistributionHostV1 {
+    readonly distribution: PluginDistributionV1;
+}
+/**
+ * Node/undici distribution transport. It is a host adapter, not Core logic:
+ * package bytes stay in a private artifact directory and are never returned by
+ * the public distribution contract.
+ */
+export declare function createNodeHttpPluginDistributionHostV1(options: NodeHttpPluginDistributionHostOptionsV1): Promise<NodeHttpPluginDistributionHostV1>;
+/**
+ * Compose the real Node HTTP transport with the explicit Ed25519 trust root.
+ * Distribution descriptors are verified before metadata or artifact access;
+ * the returned host still keeps bytes behind its private reader.
+ */
+export declare function createNodeHttpPluginDistributionStackV1(options: NodeHttpPluginDistributionStackOptionsV1): Promise<NodeHttpPluginDistributionStackV1>;
+export {};
+//# sourceMappingURL=node-distribution-host.d.ts.map

package/dist/plugins/ecosystem/node-distribution-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-distribution-host.d.ts","sourceRoot":"","sources":["../../../src/plugins/ecosystem/node-distribution-host.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEX,4BAA4B,EAE5B,wBAAwB,EAExB,oBAAoB,EACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAA+B,KAAK,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE7G,QAAA,MAAM,iCAAiC,GAAa,CAAC;AAOrD,MAAM,WAAW,uCAAuC;IACvD,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,oFAAoF;IACpF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gCAAgC;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,iCAAiC,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE;QAC9B,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;QAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;KAC9B,KAAK,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,wCAAyC,SAAQ,uCAAuC;IACxG,QAAQ,CAAC,SAAS,EAAE,4BAA4B,CAAC;IACjD,iEAAiE;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iCAAkC,SAAQ,gCAAgC;IAC1F,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;CAC5C;AA8JD;;;;GAIG;AACH,wBAAsB,sCAAsC,CAC3D,OAAO,EAAE,uCAAuC,GAC9C,OAAO,CAAC,gCAAgC,CAAC,CAmQ3C;AAED;;;;GAIG;AACH,wBAAsB,uCAAuC,CAC5D,OAAO,EAAE,wCAAwC,GAC/C,OAAO,CAAC,iCAAiC,CAAC,CAY5C","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { createReadStream } from \"node:fs\";\nimport { mkdir, mkdtemp, open, rename, rm } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { isAbsolute, join } from \"node:path\";\nimport type {\n\tPluginDistributionArtifactHandleV1,\n\tPluginDistributionArtifactV1,\n\tPluginDistributionDescriptorV1,\n\tPluginDistributionHostV1,\n\tPluginDistributionMetadataV1,\n\tPluginDistributionV1,\n} from \"./distribution.ts\";\nimport { createPluginDistributionV1 } from \"./distribution.ts\";\nimport { createNodePluginTrustRootV1, type NodePluginTrustRootOptionsV1 } from \"./node-plugin-trust-root.ts\";\n\nconst NODE_DISTRIBUTION_HOST_VERSION_V1 = 1 as const;\nconst DEFAULT_TIMEOUT_MS_V1 = 30_000;\nconst MAX_TIMEOUT_MS_V1 = 120_000;\nconst DEFAULT_REDIRECTS_V1 = 3;\nconst MAX_REDIRECTS_V1 = 5;\nconst REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);\n\nexport interface NodeHttpPluginDistributionHostOptionsV1 {\n\t/** Real `fetch` or a deterministic replacement for tests. */\n\treadonly fetch?: typeof globalThis.fetch;\n\t/** Exact `http(s)` origins. An empty allowlist is rejected. */\n\treadonly allowedOrigins: readonly string[];\n\t/** Optional host-owned directory. It is never returned as an artifact reference. */\n\treadonly artifactDirectory?: string;\n\treadonly requestTimeoutMs?: number;\n\treadonly maxRedirects?: number;\n\treadonly userAgent?: string;\n}\n\nexport interface NodeHttpPluginDistributionHostV1 {\n\treadonly version: typeof NODE_DISTRIBUTION_HOST_VERSION_V1;\n\treadonly host: PluginDistributionHostV1;\n\t/**\n\t * Private Node-host reader for an installer that shares this host instance.\n\t * It is not part of the model-facing distribution contract and never exposes\n\t * a file path. The caller must consume it before releasing the artifact.\n\t */\n\treadonly openArtifact: (input: {\n\t\treadonly artifact: PluginDistributionArtifactV1;\n\t\treadonly signal?: AbortSignal;\n\t}) => AsyncIterable<Uint8Array>;\n\t/** Remove all artifacts owned by this host instance. */\n\treadonly close: () => Promise<void>;\n}\n\n/**\n * Explicitly composed Node distribution stack. The caller supplies the trust\n * root; no key or network origin is discovered implicitly.\n */\nexport interface NodeHttpPluginDistributionStackOptionsV1 extends NodeHttpPluginDistributionHostOptionsV1 {\n\treadonly trustRoot: NodePluginTrustRootOptionsV1;\n\t/** Shared clock for descriptor expiry and trust-key validity. */\n\treadonly now?: () => number;\n}\n\nexport interface NodeHttpPluginDistributionStackV1 extends NodeHttpPluginDistributionHostV1 {\n\treadonly distribution: PluginDistributionV1;\n}\n\ninterface ArtifactRecord {\n\treadonly path: string;\n\treadonly descriptor: PluginDistributionDescriptorV1;\n\treaders: number;\n}\n\ninterface RequestSignal {\n\treadonly signal: AbortSignal;\n\treadonly timedOut: () => boolean;\n\treadonly cleanup: () => void;\n}\n\nfunction cancelledRequestError(): Error {\n\tconst error = new Error(\"plugin request was cancelled\");\n\terror.name = \"AbortError\";\n\treturn error;\n}\n\nfunction throwIfRequestCancelled(request: RequestSignal): void {\n\tif (request.timedOut()) throw new Error(\"plugin request timed out\");\n\tif (request.signal.aborted) throw cancelledRequestError();\n}\n\nfunction boundedPositive(value: number | undefined, fallback: number, maximum: number, label: string): number {\n\tconst result = value ?? fallback;\n\tif (!Number.isSafeInteger(result) || result <= 0 || result > maximum)\n\t\tthrow new Error(`${label} must be a positive integer at most ${maximum}`);\n\treturn result;\n}\n\nfunction allowedOrigin(value: string): string {\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(value);\n\t} catch {\n\t\tthrow new Error(\"allowed origin is invalid\");\n\t}\n\tif ((parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") || parsed.username || parsed.password)\n\t\tthrow new Error(\"allowed origin must be an http(s) origin\");\n\tif (parsed.pathname !== \"/\" || parsed.search !== \"\" || parsed.hash !== \"\")\n\t\tthrow new Error(\"allowed origin must not include a path or query\");\n\treturn parsed.origin;\n}\n\nfunction requestUrl(value: string, origins: ReadonlySet<string>): URL {\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(value);\n\t} catch {\n\t\tthrow new Error(\"plugin source URL is invalid\");\n\t}\n\tif ((parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") || parsed.username || parsed.password)\n\t\tthrow new Error(\"plugin source URL must use http(s) without credentials\");\n\tif (!origins.has(parsed.origin)) throw new Error(\"plugin source origin is not allowed\");\n\treturn parsed;\n}\n\nfunction requestSignal(parent: AbortSignal | undefined, timeoutMs: number): RequestSignal {\n\tconst controller = new AbortController();\n\tlet didTimeout = false;\n\tconst abort = () => controller.abort(parent?.reason);\n\tif (parent?.aborted === true) abort();\n\telse parent?.addEventListener(\"abort\", abort, { once: true });\n\tconst timeout = setTimeout(() => {\n\t\tdidTimeout = true;\n\t\tcontroller.abort();\n\t}, timeoutMs);\n\treturn {\n\t\tsignal: controller.signal,\n\t\ttimedOut: () => didTimeout,\n\t\tcleanup: () => {\n\t\t\tclearTimeout(timeout);\n\t\t\tparent?.removeEventListener(\"abort\", abort);\n\t\t},\n\t};\n}\n\nfunction contentLength(response: Response): number | undefined {\n\tconst value = response.headers.get(\"content-length\");\n\tif (value === null) return undefined;\n\tif (!/^\\d+$/u.test(value)) throw new Error(\"plugin response content length is invalid\");\n\tconst result = Number(value);\n\tif (!Number.isSafeInteger(result)) throw new Error(\"plugin response content length is invalid\");\n\treturn result;\n}\n\nfunction contentType(response: Response): string | undefined {\n\tconst value = response.headers.get(\"content-type\");\n\tif (value === null) return undefined;\n\treturn value.split(\";\", 1)[0]?.trim().toLowerCase() || undefined;\n}\n\nfunction assertResponseMetadata(response: Response, descriptor: PluginDistributionDescriptorV1): void {\n\tconst length = contentLength(response);\n\tif (length !== descriptor.sizeBytes) throw new Error(\"plugin response size mismatch\");\n\tconst mediaType = contentType(response);\n\tif (mediaType !== descriptor.mediaType.toLowerCase()) throw new Error(\"plugin response media type mismatch\");\n}\n\nasync function cancelBody(response: Response): Promise<void> {\n\tif (response.body !== null) await response.body.cancel().catch(() => undefined);\n}\n\nfunction expectedDigest(value: string): { readonly algorithm: \"sha256\" | \"sha512\"; readonly hex: string } {\n\tconst prefixed = /^(sha256|sha512):([0-9a-f]+)$/iu.exec(value);\n\tif (prefixed !== null) {\n\t\tconst algorithm = prefixed[1]?.toLowerCase();\n\t\tconst hex = prefixed[2]?.toLowerCase();\n\t\tif ((algorithm === \"sha256\" && hex?.length === 64) || (algorithm === \"sha512\" && hex?.length === 128))\n\t\t\treturn { algorithm, hex };\n\t}\n\tif (/^[0-9a-f]{64}$/iu.test(value)) return { algorithm: \"sha256\", hex: value.toLowerCase() };\n\tif (/^[0-9a-f]{128}$/iu.test(value)) return { algorithm: \"sha512\", hex: value.toLowerCase() };\n\tthrow new Error(\"plugin artifact digest algorithm is unsupported\");\n}\n\nfunction metadataFromDescriptor(descriptor: PluginDistributionDescriptorV1): PluginDistributionMetadataV1 {\n\treturn {\n\t\tversion: 1,\n\t\tsource: descriptor.source,\n\t\tpluginId: descriptor.pluginId,\n\t\tpluginVersion: descriptor.pluginVersion,\n\t\tmanifestDigest: descriptor.manifestDigest,\n\t\tartifactDigest: descriptor.artifactDigest,\n\t\texpiresAt: descriptor.expiresAt,\n\t\tsizeBytes: descriptor.sizeBytes,\n\t\tmediaType: descriptor.mediaType,\n\t};\n}\n\nfunction artifactMatchesDescriptor(\n\tartifact: PluginDistributionArtifactV1,\n\tdescriptor: PluginDistributionDescriptorV1,\n): boolean {\n\treturn (\n\t\tartifact.version === 1 &&\n\t\tartifact.pluginId === descriptor.pluginId &&\n\t\tartifact.pluginVersion === descriptor.pluginVersion &&\n\t\tartifact.manifestDigest === descriptor.manifestDigest &&\n\t\tartifact.artifactDigest === descriptor.artifactDigest &&\n\t\tartifact.sizeBytes === descriptor.sizeBytes &&\n\t\tartifact.mediaType === descriptor.mediaType &&\n\t\tartifact.source === descriptor.source &&\n\t\tartifact.expiresAt === descriptor.expiresAt\n\t);\n}\n\nasync function writeFully(file: Awaited<ReturnType<typeof open>>, chunk: Uint8Array): Promise<void> {\n\tlet offset = 0;\n\twhile (offset < chunk.byteLength) {\n\t\tconst result = await file.write(chunk, offset, chunk.byteLength - offset, null);\n\t\tif (result.bytesWritten <= 0) throw new Error(\"plugin artifact file write failed\");\n\t\toffset += result.bytesWritten;\n\t}\n}\n\n/**\n * Node/undici distribution transport. It is a host adapter, not Core logic:\n * package bytes stay in a private artifact directory and are never returned by\n * the public distribution contract.\n */\nexport async function createNodeHttpPluginDistributionHostV1(\n\toptions: NodeHttpPluginDistributionHostOptionsV1,\n): Promise<NodeHttpPluginDistributionHostV1> {\n\tconst transport = options.fetch ?? globalThis.fetch;\n\tif (typeof transport !== \"function\") throw new Error(\"Node fetch is unavailable\");\n\tif (!Array.isArray(options.allowedOrigins) || options.allowedOrigins.length === 0)\n\t\tthrow new Error(\"at least one allowed origin is required\");\n\tconst origins = new Set(options.allowedOrigins.map(allowedOrigin));\n\tconst timeoutMs = boundedPositive(\n\t\toptions.requestTimeoutMs,\n\t\tDEFAULT_TIMEOUT_MS_V1,\n\t\tMAX_TIMEOUT_MS_V1,\n\t\t\"requestTimeoutMs\",\n\t);\n\tconst maxRedirects = options.maxRedirects ?? DEFAULT_REDIRECTS_V1;\n\tif (!Number.isSafeInteger(maxRedirects) || maxRedirects < 0 || maxRedirects > MAX_REDIRECTS_V1)\n\t\tthrow new Error(`maxRedirects must be an integer between 0 and ${MAX_REDIRECTS_V1}`);\n\tconst userAgent = options.userAgent ?? \"agent-forge-plugin-distribution/1\";\n\tif (userAgent.length === 0 || userAgent.length > 256 || /[\\r\\n]/u.test(userAgent))\n\t\tthrow new Error(\"userAgent is invalid\");\n\tconst configuredDirectory = options.artifactDirectory;\n\tif (configuredDirectory !== undefined && !isAbsolute(configuredDirectory))\n\t\tthrow new Error(\"artifactDirectory must be absolute\");\n\tconst baseDirectoryPromise: Promise<string> =\n\t\tconfiguredDirectory === undefined\n\t\t\t? mkdtemp(join(tmpdir(), \"agent-forge-plugin-distribution-\"))\n\t\t\t: (async () => {\n\t\t\t\t\tawait mkdir(configuredDirectory, { recursive: true });\n\t\t\t\t\treturn await mkdtemp(join(configuredDirectory, \"agent-forge-plugin-distribution-\"));\n\t\t\t\t})();\n\tconst artifacts = new Map<string, ArtifactRecord>();\n\tconst activeOperations = new Set<AbortController>();\n\tlet operationsDrained: (() => void) | undefined;\n\tlet closePromise: Promise<void> | undefined;\n\tlet closed = false;\n\n\tconst assertOpen = (): void => {\n\t\tif (closed) throw new Error(\"plugin distribution host is closed\");\n\t};\n\n\tconst beginOperation = (): AbortController => {\n\t\tassertOpen();\n\t\tconst controller = new AbortController();\n\t\tactiveOperations.add(controller);\n\t\treturn controller;\n\t};\n\n\tconst endOperation = (controller: AbortController): void => {\n\t\tactiveOperations.delete(controller);\n\t\tif (activeOperations.size === 0) {\n\t\t\toperationsDrained?.();\n\t\t\toperationsDrained = undefined;\n\t\t}\n\t};\n\n\tconst waitForOperations = async (): Promise<void> => {\n\t\tif (activeOperations.size === 0) return;\n\t\tawait new Promise<void>((resolve) => {\n\t\t\toperationsDrained = resolve;\n\t\t});\n\t};\n\n\tconst fetchResponse = async (\n\t\tvalue: string,\n\t\tmethod: \"HEAD\" | \"GET\",\n\t\tparentSignal: AbortSignal | undefined,\n\t\toperationSignal: AbortSignal,\n\t): Promise<{ readonly response: Response; readonly request: RequestSignal }> => {\n\t\tlet current = requestUrl(value, origins);\n\t\tfor (let redirect = 0; ; redirect += 1) {\n\t\t\tif (operationSignal.aborted) throw cancelledRequestError();\n\t\t\tassertOpen();\n\t\t\tconst request = requestSignal(\n\t\t\t\tAbortSignal.any([parentSignal, operationSignal].filter(Boolean) as AbortSignal[]),\n\t\t\t\ttimeoutMs,\n\t\t\t);\n\t\t\tlet response: Response;\n\t\t\ttry {\n\t\t\t\tresponse = await transport(current.toString(), {\n\t\t\t\t\tmethod,\n\t\t\t\t\theaders: { accept: \"*/*\", \"user-agent\": userAgent },\n\t\t\t\t\tredirect: \"manual\",\n\t\t\t\t\tsignal: request.signal,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\trequest.cleanup();\n\t\t\t\tthrowIfRequestCancelled(request);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!REDIRECT_STATUS.has(response.status)) return { response, request };\n\t\t\tconst location = response.headers.get(\"location\");\n\t\t\tawait cancelBody(response);\n\t\t\trequest.cleanup();\n\t\t\tif (location === null || redirect >= maxRedirects) throw new Error(\"plugin redirect limit exceeded\");\n\t\t\tcurrent = requestUrl(new URL(location, current).toString(), origins);\n\t\t}\n\t};\n\n\tconst resolveMetadata = async (input: {\n\t\treadonly descriptor: PluginDistributionDescriptorV1;\n\t\treadonly signal?: AbortSignal;\n\t}): Promise<PluginDistributionMetadataV1> => {\n\t\tconst operation = beginOperation();\n\t\ttry {\n\t\t\tconst { response, request } = await fetchResponse(\n\t\t\t\tinput.descriptor.source,\n\t\t\t\t\"HEAD\",\n\t\t\t\tinput.signal,\n\t\t\t\toperation.signal,\n\t\t\t);\n\t\t\ttry {\n\t\t\t\tif (response.status < 200 || response.status >= 300) throw new Error(\"plugin metadata request failed\");\n\t\t\t\tassertResponseMetadata(response, input.descriptor);\n\t\t\t\treturn metadataFromDescriptor(input.descriptor);\n\t\t\t} finally {\n\t\t\t\tawait cancelBody(response);\n\t\t\t\trequest.cleanup();\n\t\t\t}\n\t\t} finally {\n\t\t\tendOperation(operation);\n\t\t}\n\t};\n\n\tconst acquireArtifact = async (input: {\n\t\treadonly descriptor: PluginDistributionDescriptorV1;\n\t\treadonly metadata: PluginDistributionMetadataV1;\n\t\treadonly signal?: AbortSignal;\n\t}): Promise<PluginDistributionArtifactHandleV1> => {\n\t\tconst operation = beginOperation();\n\t\tlet temporaryPath: string | undefined;\n\t\tlet finalPath: string | undefined;\n\t\tlet published = false;\n\t\ttry {\n\t\t\tconst digest = expectedDigest(input.descriptor.artifactDigest);\n\t\t\tconst { response, request } = await fetchResponse(\n\t\t\t\tinput.descriptor.source,\n\t\t\t\t\"GET\",\n\t\t\t\tinput.signal,\n\t\t\t\toperation.signal,\n\t\t\t);\n\t\t\tlet file: Awaited<ReturnType<typeof open>> | undefined;\n\t\t\ttry {\n\t\t\t\tif (response.status < 200 || response.status >= 300) throw new Error(\"plugin artifact request failed\");\n\t\t\t\tassertResponseMetadata(response, input.descriptor);\n\t\t\t\tif (response.body === null) throw new Error(\"plugin artifact response has no body\");\n\t\t\t\tconst directory = await baseDirectoryPromise;\n\t\t\t\ttemporaryPath = join(directory, `.partial-${randomUUID()}`);\n\t\t\t\tfinalPath = join(directory, `artifact-${randomUUID()}`);\n\t\t\t\tfile = await open(temporaryPath, \"wx\");\n\t\t\t\tconst reader = response.body.getReader();\n\t\t\t\tconst hash = createHash(digest.algorithm);\n\t\t\t\tlet total = 0;\n\t\t\t\ttry {\n\t\t\t\t\tfor (;;) {\n\t\t\t\t\t\tthrowIfRequestCancelled(request);\n\t\t\t\t\t\tconst item = await reader.read();\n\t\t\t\t\t\tif (item.done) break;\n\t\t\t\t\t\tconst chunk = item.value;\n\t\t\t\t\t\ttotal += chunk.byteLength;\n\t\t\t\t\t\tif (total > input.descriptor.sizeBytes) throw new Error(\"plugin artifact exceeds its size limit\");\n\t\t\t\t\t\thash.update(chunk);\n\t\t\t\t\t\tawait writeFully(file, chunk);\n\t\t\t\t\t}\n\t\t\t\t} finally {\n\t\t\t\t\treader.releaseLock();\n\t\t\t\t}\n\t\t\t\tthrowIfRequestCancelled(request);\n\t\t\t\tif (total !== input.descriptor.sizeBytes) throw new Error(\"plugin artifact size mismatch\");\n\t\t\t\tif (hash.digest(\"hex\") !== digest.hex) throw new Error(\"plugin artifact digest mismatch\");\n\t\t\t\tawait file.close();\n\t\t\t\tfile = undefined;\n\t\t\t\tawait rename(temporaryPath, finalPath);\n\t\t\t\tassertOpen();\n\t\t\t\tconst artifactRef = `artifact://node-http/${randomUUID()}`;\n\t\t\t\tartifacts.set(artifactRef, { path: finalPath, descriptor: input.descriptor, readers: 0 });\n\t\t\t\tpublished = true;\n\t\t\t\treturn {\n\t\t\t\t\tartifactRef,\n\t\t\t\t\tartifactDigest: input.descriptor.artifactDigest,\n\t\t\t\t\tsizeBytes: input.descriptor.sizeBytes,\n\t\t\t\t\tmediaType: input.descriptor.mediaType,\n\t\t\t\t};\n\t\t\t} catch (error) {\n\t\t\t\tthrowIfRequestCancelled(request);\n\t\t\t\tthrow error;\n\t\t\t} finally {\n\t\t\t\tif (file !== undefined) await file.close().catch(() => undefined);\n\t\t\t\tawait cancelBody(response);\n\t\t\t\trequest.cleanup();\n\t\t\t}\n\t\t} finally {\n\t\t\tif (temporaryPath !== undefined) await rm(temporaryPath, { force: true }).catch(() => undefined);\n\t\t\tif (!published && finalPath !== undefined) await rm(finalPath, { force: true }).catch(() => undefined);\n\t\t\tendOperation(operation);\n\t\t}\n\t};\n\n\tconst releaseArtifact = async (input: {\n\t\treadonly artifact: { readonly artifactRef: string };\n\t\treadonly signal?: AbortSignal;\n\t}): Promise<void> => {\n\t\tassertOpen();\n\t\tif (input.signal?.aborted) throw new Error(\"plugin artifact release was cancelled\");\n\t\tconst record = artifacts.get(input.artifact.artifactRef);\n\t\tif (record === undefined) throw new Error(\"plugin artifact reference is unknown\");\n\t\tif (record.readers > 0) throw new Error(\"plugin artifact is still being read\");\n\t\tawait rm(record.path, { force: false });\n\t\tartifacts.delete(input.artifact.artifactRef);\n\t};\n\n\tconst openArtifact = (input: {\n\t\treadonly artifact: PluginDistributionArtifactV1;\n\t\treadonly signal?: AbortSignal;\n\t}): AsyncIterable<Uint8Array> =>\n\t\t(async function* (): AsyncGenerator<Uint8Array> {\n\t\t\tconst operation = beginOperation();\n\t\t\tlet stream: ReturnType<typeof createReadStream> | undefined;\n\t\t\tlet acquiredRecord: ArtifactRecord | undefined;\n\t\t\tconst abort = () => stream?.destroy(new Error(\"plugin artifact read was cancelled\"));\n\t\t\ttry {\n\t\t\t\tif (input.signal?.aborted) throw new Error(\"plugin artifact read was cancelled\");\n\t\t\t\tconst record = artifacts.get(input.artifact.artifactRef);\n\t\t\t\tif (record === undefined || !artifactMatchesDescriptor(input.artifact, record.descriptor))\n\t\t\t\t\tthrow new Error(\"plugin artifact reference is unknown\");\n\t\t\t\trecord.readers += 1;\n\t\t\t\tacquiredRecord = record;\n\t\t\t\tstream = createReadStream(record.path, { highWaterMark: 64 * 1024 });\n\t\t\t\tinput.signal?.addEventListener(\"abort\", abort, { once: true });\n\t\t\t\toperation.signal.addEventListener(\"abort\", abort, { once: true });\n\t\t\t\tfor await (const chunk of stream) {\n\t\t\t\t\tif (input.signal?.aborted || operation.signal.aborted)\n\t\t\t\t\t\tthrow new Error(\"plugin artifact read was cancelled\");\n\t\t\t\t\tyield new Uint8Array(chunk);\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tinput.signal?.removeEventListener(\"abort\", abort);\n\t\t\t\toperation.signal.removeEventListener(\"abort\", abort);\n\t\t\t\tstream?.destroy();\n\t\t\t\tif (acquiredRecord !== undefined && acquiredRecord.readers > 0) acquiredRecord.readers -= 1;\n\t\t\t\tendOperation(operation);\n\t\t\t}\n\t\t})();\n\n\treturn {\n\t\tversion: NODE_DISTRIBUTION_HOST_VERSION_V1,\n\t\thost: { resolveMetadata, acquireArtifact, releaseArtifact },\n\t\topenArtifact,\n\t\tclose: async () => {\n\t\t\tif (closePromise !== undefined) return await closePromise;\n\t\t\tclosed = true;\n\t\t\tfor (const operation of activeOperations) operation.abort();\n\t\t\tclosePromise = (async () => {\n\t\t\t\tawait waitForOperations();\n\t\t\t\tconst directory = await baseDirectoryPromise;\n\t\t\t\tawait Promise.all([...artifacts.values()].map((record) => rm(record.path, { force: true })));\n\t\t\t\tartifacts.clear();\n\t\t\t\tawait rm(directory, { recursive: true, force: true });\n\t\t\t})();\n\t\t\treturn await closePromise;\n\t\t},\n\t};\n}\n\n/**\n * Compose the real Node HTTP transport with the explicit Ed25519 trust root.\n * Distribution descriptors are verified before metadata or artifact access;\n * the returned host still keeps bytes behind its private reader.\n */\nexport async function createNodeHttpPluginDistributionStackV1(\n\toptions: NodeHttpPluginDistributionStackOptionsV1,\n): Promise<NodeHttpPluginDistributionStackV1> {\n\tconst { trustRoot, now: configuredNow, ...hostOptions } = options;\n\tconst host = await createNodeHttpPluginDistributionHostV1(hostOptions);\n\ttry {\n\t\tconst now = configuredNow ?? trustRoot.now ?? (() => Date.now());\n\t\tconst verifySignature = createNodePluginTrustRootV1({ ...trustRoot, now });\n\t\tconst distribution = createPluginDistributionV1({ host: host.host, verifySignature, now });\n\t\treturn Object.freeze({ ...host, distribution });\n\t} catch (error) {\n\t\tawait host.close().catch(() => undefined);\n\t\tthrow error;\n\t}\n}\n"]}