@ai-agent-forge/agent-forge 0.85.0

package/dist/plugins/ecosystem/default-plugin-market.js

@@ -0,0 +1,146 @@
+/**
+ * Default CLI wiring for the plugin marketplace write side (P1-5): one
+ * factory composes the disk install store, an optional HTTP registry origin,
+ * the HTTP distribution host, and the persistent package install host into
+ * the registry/installer/distribution surfaces the ecosystem CLI and the TUI
+ * manager consume. Nothing here discovers keys or origins implicitly: the
+ * registry origin comes from an explicit option or the
+ * AGENT_FORGE_PLUGIN_REGISTRY_ORIGIN environment variable, and its absence
+ * keeps disk-only semantics (install resolves to not_found, remove/rollback
+ * and state management stay fully usable). Host injection always wins; the
+ * factory is only invoked when no host-supplied boundary exists.
+ */
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "../../config.js";
+import { DEFAULT_PLUGIN_STATE_FILE_V1, defaultPluginHostFactsV1, defaultPluginInstallStoreDirectoryV1, defaultPluginInstallStoreInstanceRootV1, } from "./default-active-bindings.js";
+import { createPluginDistributionV1 } from "./distribution.js";
+import { createPluginInstallerV1 } from "./installer.js";
+import { createNodeDiskPluginRegistrySourceV1 } from "./node-disk-registry-source.js";
+import { createNodeHttpPluginDistributionHostV1, } from "./node-distribution-host.js";
+import { createNodePackageInstallHostV1, NodePackageInstallErrorV1, } from "./node-package-install-host.js";
+import { createNodePluginAcquisitionHostV1 } from "./node-plugin-acquisition-host.js";
+import { createNodePluginTrustRootV1 } from "./node-plugin-trust-root.js";
+import { createNodeHttpPluginRegistrySourceV1 } from "./node-registry-source.js";
+import { createPluginRegistryV1 } from "./registry.js";
+import { createPluginEcosystemRegistryAdapterV1 } from "./registry-cli-adapter.js";
+import { createPluginStateStoreV1 } from "./state.js";
+/** Environment variable carrying the exact http(s) marketplace origin. */
+export const DEFAULT_PLUGIN_REGISTRY_ORIGIN_ENV_V1 = "AGENT_FORGE_PLUGIN_REGISTRY_ORIGIN";
+/**
+ * Environment variable carrying the Ed25519 trust root as a JSON array of
+ * `{keyId, publicKeyPem}` entries. Downloads never verify without an explicit
+ * trust root; there is no implicit key discovery.
+ */
+export const DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1 = "AGENT_FORGE_PLUGIN_TRUST_KEYS";
+/** Registry document path below the configured origin. */
+export const DEFAULT_PLUGIN_REGISTRY_PATH_V1 = "/v1/plugin-registry.json";
+/**
+ * Compose the default marketplace boundaries over one agent directory. The
+ * disk install store is always part of the registry so installed plugins can
+ * be listed, updated, and removed offline; a configured origin adds the HTTP
+ * registry and package download. Installation failures surface structured
+ * errors, never synthetic success.
+ */
+export async function createDefaultPluginMarketWiringV1(options) {
+    const origin = (options.registryOrigin ?? process.env[DEFAULT_PLUGIN_REGISTRY_ORIGIN_ENV_V1])?.trim();
+    const effectiveOrigin = origin === "" ? undefined : origin;
+    const storeParent = defaultPluginInstallStoreDirectoryV1(options.agentDir);
+    // The install host persists under this fixed subdirectory; the disk
+    // registry source must read the same instance root to observe installs.
+    const instanceRoot = defaultPluginInstallStoreInstanceRootV1(options.agentDir);
+    const diskSource = createNodeDiskPluginRegistrySourceV1({ rootDirectory: instanceRoot });
+    const httpSource = effectiveOrigin === undefined
+        ? undefined
+        : createNodeHttpPluginRegistrySourceV1({
+            url: new URL(effectiveOrigin + DEFAULT_PLUGIN_REGISTRY_PATH_V1),
+            allowedOrigins: [effectiveOrigin],
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        });
+    const source = {
+        ...(httpSource === undefined ? {} : { source: httpSource.source }),
+        list: async ({ signal } = {}) => {
+            const disk = await diskSource.list({ signal });
+            if (httpSource === undefined)
+                return disk;
+            const remote = await httpSource.list({ signal });
+            return Object.freeze([...remote, ...disk]);
+        },
+    };
+    const distributionHost = effectiveOrigin === undefined
+        ? undefined
+        : await createNodeHttpPluginDistributionHostV1({
+            allowedOrigins: [effectiveOrigin],
+            artifactDirectory: join(storeParent, "distribution-cache-v1"),
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        });
+    let trustKeys = options.trustKeys;
+    if (trustKeys === undefined && effectiveOrigin !== undefined) {
+        const raw = process.env[DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1];
+        if (raw !== undefined && raw.trim() !== "") {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`${DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1} must be a JSON array of {keyId, publicKeyPem}`);
+            }
+            if (!Array.isArray(parsed))
+                throw new Error(`${DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1} must be a JSON array`);
+            trustKeys = parsed;
+        }
+    }
+    const trustRoot = trustKeys === undefined || distributionHost === undefined
+        ? undefined
+        : createNodePluginTrustRootV1({ keys: trustKeys });
+    // Acquisition artifacts (npm/URL/local refs) and signed distribution
+    // artifacts share one install host; ownership decides which reader serves.
+    const acquisitionHost = options.acquisition ??
+        createNodePluginAcquisitionHostV1({
+            ...(options.limits === undefined ? {} : { limits: options.limits }),
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        });
+    const openArtifact = (input) => {
+        if (acquisitionHost.ownsArtifact(input.artifact))
+            return acquisitionHost.openArtifact(input);
+        const reader = distributionHost?.openArtifact;
+        if (reader === undefined)
+            throw new NodePackageInstallErrorV1("invalid_artifact");
+        return reader(input);
+    };
+    const installHost = await createNodePackageInstallHostV1({
+        openArtifact,
+        installationDirectory: storeParent,
+        persistence: "persistent",
+        supportedScopes: ["global", "project"],
+        ...(options.limits === undefined ? {} : { ...options.limits }),
+    });
+    const registry = createPluginRegistryV1({
+        source,
+        host: defaultPluginHostFactsV1(),
+        verify: {
+            verify: ({ manifestDigest, expectedDigest }) => expectedDigest === undefined || expectedDigest === manifestDigest
+                ? { status: "accepted" }
+                : { status: "rejected", reason: "Manifest digest does not match the expected digest" },
+        },
+        sourceVerifier: () => ({ status: "accepted" }),
+    });
+    return {
+        registry,
+        cliRegistry: createPluginEcosystemRegistryAdapterV1(registry),
+        acquisition: acquisitionHost,
+        installer: createPluginInstallerV1({ host: installHost }),
+        ...(distributionHost === undefined || trustRoot === undefined
+            ? {}
+            : { distribution: createPluginDistributionV1({ host: distributionHost.host, verifySignature: trustRoot }) }),
+        stateStore: createPluginStateStoreV1({ filePath: join(options.agentDir, DEFAULT_PLUGIN_STATE_FILE_V1) }),
+        projectStateStore: createPluginStateStoreV1({
+            filePath: join(options.cwd, CONFIG_DIR_NAME, DEFAULT_PLUGIN_STATE_FILE_V1),
+        }),
+        close: async () => {
+            await installHost.close();
+            await acquisitionHost.close();
+            await distributionHost?.close();
+        },
+    };
+}
+//# sourceMappingURL=default-plugin-market.js.map

package/dist/plugins/ecosystem/default-plugin-market.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-plugin-market.js","sourceRoot":"","sources":["../../../src/plugins/ecosystem/default-plugin-market.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Default CLI wiring for the plugin marketplace write side (P1-5): one\n * factory composes the disk install store, an optional HTTP registry origin,\n * the HTTP distribution host, and the persistent package install host into\n * the registry/installer/distribution surfaces the ecosystem CLI and the TUI\n * manager consume. Nothing here discovers keys or origins implicitly: the\n * registry origin comes from an explicit option or the\n * AGENT_FORGE_PLUGIN_REGISTRY_ORIGIN environment variable, and its absence\n * keeps disk-only semantics (install resolves to not_found, remove/rollback\n * and state management stay fully usable). Host injection always wins; the\n * factory is only invoked when no host-supplied boundary exists.\n */\n\nimport { join } from \"node:path\";\nimport { CONFIG_DIR_NAME } from \"../../config.ts\";\nimport type { PluginEcosystemRegistryV1 } from \"./cli.ts\";\nimport {\n\tDEFAULT_PLUGIN_STATE_FILE_V1,\n\tdefaultPluginHostFactsV1,\n\tdefaultPluginInstallStoreDirectoryV1,\n\tdefaultPluginInstallStoreInstanceRootV1,\n} from \"./default-active-bindings.ts\";\nimport { createPluginDistributionV1, type PluginDistributionV1 } from \"./distribution.ts\";\nimport { createPluginInstallerV1, type PluginInstallerV1 } from \"./installer.ts\";\nimport { createNodeDiskPluginRegistrySourceV1 } from \"./node-disk-registry-source.ts\";\nimport {\n\tcreateNodeHttpPluginDistributionHostV1,\n\ttype NodeHttpPluginDistributionHostV1,\n} from \"./node-distribution-host.ts\";\nimport {\n\tcreateNodePackageInstallHostV1,\n\tNodePackageInstallErrorV1,\n\ttype NodeZipPackageLimitsV1,\n} from \"./node-package-install-host.ts\";\nimport { createNodePluginAcquisitionHostV1, type NodePluginAcquisitionHostV1 } from \"./node-plugin-acquisition-host.ts\";\nimport { createNodePluginTrustRootV1, type NodePluginTrustRootKeyV1 } from \"./node-plugin-trust-root.ts\";\nimport { createNodeHttpPluginRegistrySourceV1 } from \"./node-registry-source.ts\";\nimport { createPluginRegistryV1, type PluginRegistrySourceV1, type PluginRegistryV1 } from \"./registry.ts\";\nimport { createPluginEcosystemRegistryAdapterV1 } from \"./registry-cli-adapter.ts\";\nimport { createPluginStateStoreV1, type PluginStateStoreV1 } from \"./state.ts\";\n\n/** Environment variable carrying the exact http(s) marketplace origin. */\nexport const DEFAULT_PLUGIN_REGISTRY_ORIGIN_ENV_V1 = \"AGENT_FORGE_PLUGIN_REGISTRY_ORIGIN\";\n\n/**\n * Environment variable carrying the Ed25519 trust root as a JSON array of\n * `{keyId, publicKeyPem}` entries. Downloads never verify without an explicit\n * trust root; there is no implicit key discovery.\n */\nexport const DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1 = \"AGENT_FORGE_PLUGIN_TRUST_KEYS\";\n\n/** Registry document path below the configured origin. */\nexport const DEFAULT_PLUGIN_REGISTRY_PATH_V1 = \"/v1/plugin-registry.json\";\n\nexport interface DefaultPluginMarketOptionsV1 {\n\treadonly agentDir: string;\n\treadonly cwd: string;\n\t/** Exact http(s) registry origin; defaults to the environment variable. */\n\treadonly registryOrigin?: string;\n\t/** Explicit Ed25519 trust root; defaults to the environment variable. */\n\treadonly trustKeys?: readonly NodePluginTrustRootKeyV1[];\n\t/** Optional acquisition host override (tests); defaults to a real Node host. */\n\treadonly acquisition?: NodePluginAcquisitionHostV1;\n\t/** Optional package limits shared by acquisition and the install host; defaults apply. */\n\treadonly limits?: NodeZipPackageLimitsV1;\n\t/** Deterministic fetch replacement for tests. */\n\treadonly fetch?: typeof globalThis.fetch;\n}\n\nexport interface DefaultPluginMarketWiringV1 {\n\t/** Verified registry for the manager controller snapshot. */\n\treadonly registry: PluginRegistryV1;\n\t/** CLI-facing adapter over the same verified registry. */\n\treadonly cliRegistry: PluginEcosystemRegistryV1;\n\t/** Multi-source acquisition boundary for `plugin install <ref>`. */\n\treadonly acquisition: NodePluginAcquisitionHostV1;\n\treadonly installer: PluginInstallerV1;\n\t/** Present only when a registry origin is configured. */\n\treadonly distribution?: PluginDistributionV1;\n\treadonly stateStore: PluginStateStoreV1;\n\treadonly projectStateStore: PluginStateStoreV1;\n\t/** Releases the distribution host's cached artifacts when present. */\n\treadonly close: () => Promise<void>;\n}\n\n/**\n * Compose the default marketplace boundaries over one agent directory. The\n * disk install store is always part of the registry so installed plugins can\n * be listed, updated, and removed offline; a configured origin adds the HTTP\n * registry and package download. Installation failures surface structured\n * errors, never synthetic success.\n */\nexport async function createDefaultPluginMarketWiringV1(\n\toptions: DefaultPluginMarketOptionsV1,\n): Promise<DefaultPluginMarketWiringV1> {\n\tconst origin = (options.registryOrigin ?? process.env[DEFAULT_PLUGIN_REGISTRY_ORIGIN_ENV_V1])?.trim();\n\tconst effectiveOrigin = origin === \"\" ? undefined : origin;\n\tconst storeParent = defaultPluginInstallStoreDirectoryV1(options.agentDir);\n\t// The install host persists under this fixed subdirectory; the disk\n\t// registry source must read the same instance root to observe installs.\n\tconst instanceRoot = defaultPluginInstallStoreInstanceRootV1(options.agentDir);\n\tconst diskSource = createNodeDiskPluginRegistrySourceV1({ rootDirectory: instanceRoot });\n\tconst httpSource =\n\t\teffectiveOrigin === undefined\n\t\t\t? undefined\n\t\t\t: createNodeHttpPluginRegistrySourceV1({\n\t\t\t\t\turl: new URL(effectiveOrigin + DEFAULT_PLUGIN_REGISTRY_PATH_V1),\n\t\t\t\t\tallowedOrigins: [effectiveOrigin],\n\t\t\t\t\t...(options.fetch === undefined ? {} : { fetch: options.fetch }),\n\t\t\t\t});\n\tconst source: PluginRegistrySourceV1 = {\n\t\t...(httpSource === undefined ? {} : { source: httpSource.source }),\n\t\tlist: async ({ signal } = {}) => {\n\t\t\tconst disk = await diskSource.list({ signal });\n\t\t\tif (httpSource === undefined) return disk;\n\t\t\tconst remote = await httpSource.list({ signal });\n\t\t\treturn Object.freeze([...remote, ...disk]);\n\t\t},\n\t};\n\tconst distributionHost =\n\t\teffectiveOrigin === undefined\n\t\t\t? undefined\n\t\t\t: await createNodeHttpPluginDistributionHostV1({\n\t\t\t\t\tallowedOrigins: [effectiveOrigin],\n\t\t\t\t\tartifactDirectory: join(storeParent, \"distribution-cache-v1\"),\n\t\t\t\t\t...(options.fetch === undefined ? {} : { fetch: options.fetch }),\n\t\t\t\t});\n\tlet trustKeys = options.trustKeys;\n\tif (trustKeys === undefined && effectiveOrigin !== undefined) {\n\t\tconst raw = process.env[DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1];\n\t\tif (raw !== undefined && raw.trim() !== \"\") {\n\t\t\tlet parsed: unknown;\n\t\t\ttry {\n\t\t\t\tparsed = JSON.parse(raw);\n\t\t\t} catch {\n\t\t\t\tthrow new Error(`${DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1} must be a JSON array of {keyId, publicKeyPem}`);\n\t\t\t}\n\t\t\tif (!Array.isArray(parsed)) throw new Error(`${DEFAULT_PLUGIN_TRUST_KEYS_ENV_V1} must be a JSON array`);\n\t\t\ttrustKeys = parsed as NodePluginTrustRootKeyV1[];\n\t\t}\n\t}\n\tconst trustRoot =\n\t\ttrustKeys === undefined || distributionHost === undefined\n\t\t\t? undefined\n\t\t\t: createNodePluginTrustRootV1({ keys: trustKeys });\n\t// Acquisition artifacts (npm/URL/local refs) and signed distribution\n\t// artifacts share one install host; ownership decides which reader serves.\n\tconst acquisitionHost =\n\t\toptions.acquisition ??\n\t\tcreateNodePluginAcquisitionHostV1({\n\t\t\t...(options.limits === undefined ? {} : { limits: options.limits }),\n\t\t\t...(options.fetch === undefined ? {} : { fetch: options.fetch }),\n\t\t});\n\tconst openArtifact: NodeHttpPluginDistributionHostV1[\"openArtifact\"] = (input) => {\n\t\tif (acquisitionHost.ownsArtifact(input.artifact)) return acquisitionHost.openArtifact(input);\n\t\tconst reader = distributionHost?.openArtifact;\n\t\tif (reader === undefined) throw new NodePackageInstallErrorV1(\"invalid_artifact\");\n\t\treturn reader(input);\n\t};\n\tconst installHost = await createNodePackageInstallHostV1({\n\t\topenArtifact,\n\t\tinstallationDirectory: storeParent,\n\t\tpersistence: \"persistent\",\n\t\tsupportedScopes: [\"global\", \"project\"],\n\t\t...(options.limits === undefined ? {} : { ...options.limits }),\n\t});\n\tconst registry = createPluginRegistryV1({\n\t\tsource,\n\t\thost: defaultPluginHostFactsV1(),\n\t\tverify: {\n\t\t\tverify: ({ manifestDigest, expectedDigest }) =>\n\t\t\t\texpectedDigest === undefined || expectedDigest === manifestDigest\n\t\t\t\t\t? { status: \"accepted\" }\n\t\t\t\t\t: { status: \"rejected\", reason: \"Manifest digest does not match the expected digest\" },\n\t\t},\n\t\tsourceVerifier: () => ({ status: \"accepted\" }),\n\t});\n\treturn {\n\t\tregistry,\n\t\tcliRegistry: createPluginEcosystemRegistryAdapterV1(registry),\n\t\tacquisition: acquisitionHost,\n\t\tinstaller: createPluginInstallerV1({ host: installHost }),\n\t\t...(distributionHost === undefined || trustRoot === undefined\n\t\t\t? {}\n\t\t\t: { distribution: createPluginDistributionV1({ host: distributionHost.host, verifySignature: trustRoot }) }),\n\t\tstateStore: createPluginStateStoreV1({ filePath: join(options.agentDir, DEFAULT_PLUGIN_STATE_FILE_V1) }),\n\t\tprojectStateStore: createPluginStateStoreV1({\n\t\t\tfilePath: join(options.cwd, CONFIG_DIR_NAME, DEFAULT_PLUGIN_STATE_FILE_V1),\n\t\t}),\n\t\tclose: async () => {\n\t\t\tawait installHost.close();\n\t\t\tawait acquisitionHost.close();\n\t\t\tawait distributionHost?.close();\n\t\t},\n\t};\n}\n"]}

package/dist/plugins/ecosystem/distribution.d.ts

@@ -0,0 +1,113 @@
+/** Distribution contract version. The host and package must agree on this version. */
+export declare const PLUGIN_DISTRIBUTION_CONTRACT_VERSION_V1: 1;
+/** Maximum serialized descriptor size crossing the registry boundary. */
+export declare const MAX_PLUGIN_DISTRIBUTION_DESCRIPTOR_BYTES_V1: number;
+/** Maximum length of identity, URI, digest, signature, and media-type fields. */
+export declare const MAX_PLUGIN_DISTRIBUTION_FIELD_CHARS_V1 = 2048;
+/** Maximum descriptor metadata size returned by a host. */
+export declare const MAX_PLUGIN_DISTRIBUTION_METADATA_BYTES_V1: number;
+/** Maximum opaque artifact handle length. */
+export declare const MAX_PLUGIN_DISTRIBUTION_ARTIFACT_REF_CHARS_V1 = 2048;
+/** Maximum package size accepted by this contract. Larger artifacts need a newer contract. */
+export declare const MAX_PLUGIN_DISTRIBUTION_ARTIFACT_BYTES_V1: number;
+/** A signed, bounded package descriptor. It contains no package bytes or local path. */
+export interface PluginDistributionDescriptorV1 {
+    readonly version: 1;
+    readonly source: string;
+    readonly pluginId: string;
+    readonly pluginVersion: string;
+    readonly manifestDigest: string;
+    readonly artifactDigest: string;
+    readonly signature: string;
+    readonly expiresAt: string;
+    readonly sizeBytes: number;
+    readonly mediaType: string;
+}
+/** Metadata resolved by a host before any artifact is acquired. */
+export interface PluginDistributionMetadataV1 {
+    readonly version: 1;
+    readonly source: string;
+    readonly pluginId: string;
+    readonly pluginVersion: string;
+    readonly manifestDigest: string;
+    readonly artifactDigest: string;
+    readonly expiresAt: string;
+    readonly sizeBytes: number;
+    readonly mediaType: string;
+}
+/** Host-owned acquisition result. `artifactRef` is opaque and is never a path. */
+export interface PluginDistributionArtifactHandleV1 {
+    readonly artifactRef: string;
+    readonly artifactDigest: string;
+    readonly sizeBytes: number;
+    readonly mediaType: string;
+}
+/** Model-facing acquisition projection. It deliberately contains no bytes or metadata payload. */
+export interface PluginDistributionArtifactV1 extends PluginDistributionMetadataV1 {
+    readonly artifactRef: string;
+}
+export interface PluginDistributionSignatureVerificationInputV1 {
+    readonly descriptor: PluginDistributionDescriptorV1;
+}
+export type PluginDistributionSignatureVerificationV1 = {
+    readonly status: "accepted";
+} | {
+    readonly status: "rejected";
+    readonly reason?: string;
+};
+export type PluginDistributionSignatureVerifierV1 = (input: PluginDistributionSignatureVerificationInputV1) => PluginDistributionSignatureVerificationV1 | Promise<PluginDistributionSignatureVerificationV1>;
+/**
+ * Host boundary for registry metadata and package bytes. The core never opens a
+ * URL, reads a path, or receives package bytes; hosts return only bounded metadata
+ * and opaque artifact references.
+ */
+export interface PluginDistributionHostV1 {
+    readonly resolveMetadata?: (input: {
+        readonly descriptor: PluginDistributionDescriptorV1;
+        readonly signal?: AbortSignal;
+    }) => Promise<PluginDistributionMetadataV1>;
+    readonly acquireArtifact?: (input: {
+        readonly descriptor: PluginDistributionDescriptorV1;
+        readonly metadata: PluginDistributionMetadataV1;
+        readonly signal?: AbortSignal;
+    }) => Promise<PluginDistributionArtifactHandleV1>;
+    readonly releaseArtifact?: (input: {
+        readonly artifact: PluginDistributionArtifactV1;
+        readonly signal?: AbortSignal;
+    }) => Promise<void>;
+}
+export interface PluginDistributionOptionsV1 {
+    readonly host?: PluginDistributionHostV1;
+    /** Required for trust. There is no implicit signature acceptance fallback. */
+    readonly verifySignature?: PluginDistributionSignatureVerifierV1;
+    /** Alias for callers using the registry verifier naming. */
+    readonly verify?: PluginDistributionSignatureVerifierV1;
+    /** Injected clock for deterministic tests; returns epoch milliseconds. */
+    readonly now?: () => number;
+}
+export type PluginDistributionErrorCodeV1 = "unsupported" | "cancelled" | "invalid_descriptor" | "invalid_metadata" | "invalid_artifact" | "source_mismatch" | "identity_mismatch" | "digest_mismatch" | "signature_invalid" | "expired" | "size_mismatch" | "media_type_mismatch" | "host_failed" | "release_failed";
+/** Stable, non-leaking distribution error. Host exception messages are never retained. */
+export declare class PluginDistributionErrorV1 extends Error {
+    readonly code: PluginDistributionErrorCodeV1;
+    constructor(code: PluginDistributionErrorCodeV1);
+}
+export interface PluginDistributionV1 {
+    /** Validate and detach a descriptor before passing it to a host or verifier. */
+    validateDescriptor(input: unknown): PluginDistributionDescriptorV1;
+    resolveMetadata(input: {
+        descriptor: unknown;
+        signal?: AbortSignal;
+    }): Promise<PluginDistributionMetadataV1>;
+    acquireArtifact(input: {
+        descriptor: unknown;
+        metadata?: unknown;
+        signal?: AbortSignal;
+    }): Promise<PluginDistributionArtifactV1>;
+    releaseArtifact(input: {
+        artifact: unknown;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Create a host-injected distribution client. No host means all side effects are unsupported. */
+export declare function createPluginDistributionV1(options?: PluginDistributionOptionsV1): PluginDistributionV1;
+//# sourceMappingURL=distribution.d.ts.map

package/dist/plugins/ecosystem/distribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../../src/plugins/ecosystem/distribution.ts"],"names":[],"mappings":"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","sourcesContent":["import { detachedFreeze, isPlainRecord } from \"@agent-forge/plugin-sdk\";\n\n/** Distribution contract version. The host and package must agree on this version. */\nexport const PLUGIN_DISTRIBUTION_CONTRACT_VERSION_V1 = 1 as const;\n\n/** Maximum serialized descriptor size crossing the registry boundary. */\nexport const MAX_PLUGIN_DISTRIBUTION_DESCRIPTOR_BYTES_V1 = 16 * 1024;\n/** Maximum length of identity, URI, digest, signature, and media-type fields. */\nexport const MAX_PLUGIN_DISTRIBUTION_FIELD_CHARS_V1 = 2048;\n/** Maximum descriptor metadata size returned by a host. */\nexport const MAX_PLUGIN_DISTRIBUTION_METADATA_BYTES_V1 = 16 * 1024;\n/** Maximum opaque artifact handle length. */\nexport const MAX_PLUGIN_DISTRIBUTION_ARTIFACT_REF_CHARS_V1 = 2048;\n/** Maximum package size accepted by this contract. Larger artifacts need a newer contract. */\nexport const MAX_PLUGIN_DISTRIBUTION_ARTIFACT_BYTES_V1 = 512 * 1024 * 1024;\n\n/** A signed, bounded package descriptor. It contains no package bytes or local path. */\nexport interface PluginDistributionDescriptorV1 {\n\treadonly version: 1;\n\treadonly source: string;\n\treadonly pluginId: string;\n\treadonly pluginVersion: string;\n\treadonly manifestDigest: string;\n\treadonly artifactDigest: string;\n\treadonly signature: string;\n\treadonly expiresAt: string;\n\treadonly sizeBytes: number;\n\treadonly mediaType: string;\n}\n\n/** Metadata resolved by a host before any artifact is acquired. */\nexport interface PluginDistributionMetadataV1 {\n\treadonly version: 1;\n\treadonly source: string;\n\treadonly pluginId: string;\n\treadonly pluginVersion: string;\n\treadonly manifestDigest: string;\n\treadonly artifactDigest: string;\n\treadonly expiresAt: string;\n\treadonly sizeBytes: number;\n\treadonly mediaType: string;\n}\n\n/** Host-owned acquisition result. `artifactRef` is opaque and is never a path. */\nexport interface PluginDistributionArtifactHandleV1 {\n\treadonly artifactRef: string;\n\treadonly artifactDigest: string;\n\treadonly sizeBytes: number;\n\treadonly mediaType: string;\n}\n\n/** Model-facing acquisition projection. It deliberately contains no bytes or metadata payload. */\nexport interface PluginDistributionArtifactV1 extends PluginDistributionMetadataV1 {\n\treadonly artifactRef: string;\n}\n\nexport interface PluginDistributionSignatureVerificationInputV1 {\n\treadonly descriptor: PluginDistributionDescriptorV1;\n}\n\nexport type PluginDistributionSignatureVerificationV1 =\n\t| { readonly status: \"accepted\" }\n\t| { readonly status: \"rejected\"; readonly reason?: string };\n\nexport type PluginDistributionSignatureVerifierV1 = (\n\tinput: PluginDistributionSignatureVerificationInputV1,\n) => PluginDistributionSignatureVerificationV1 | Promise<PluginDistributionSignatureVerificationV1>;\n\n/**\n * Host boundary for registry metadata and package bytes. The core never opens a\n * URL, reads a path, or receives package bytes; hosts return only bounded metadata\n * and opaque artifact references.\n */\nexport interface PluginDistributionHostV1 {\n\treadonly resolveMetadata?: (input: {\n\t\treadonly descriptor: PluginDistributionDescriptorV1;\n\t\treadonly signal?: AbortSignal;\n\t}) => Promise<PluginDistributionMetadataV1>;\n\treadonly acquireArtifact?: (input: {\n\t\treadonly descriptor: PluginDistributionDescriptorV1;\n\t\treadonly metadata: PluginDistributionMetadataV1;\n\t\treadonly signal?: AbortSignal;\n\t}) => Promise<PluginDistributionArtifactHandleV1>;\n\treadonly releaseArtifact?: (input: {\n\t\treadonly artifact: PluginDistributionArtifactV1;\n\t\treadonly signal?: AbortSignal;\n\t}) => Promise<void>;\n}\n\nexport interface PluginDistributionOptionsV1 {\n\treadonly host?: PluginDistributionHostV1;\n\t/** Required for trust. There is no implicit signature acceptance fallback. */\n\treadonly verifySignature?: PluginDistributionSignatureVerifierV1;\n\t/** Alias for callers using the registry verifier naming. */\n\treadonly verify?: PluginDistributionSignatureVerifierV1;\n\t/** Injected clock for deterministic tests; returns epoch milliseconds. */\n\treadonly now?: () => number;\n}\n\nexport type PluginDistributionErrorCodeV1 =\n\t| \"unsupported\"\n\t| \"cancelled\"\n\t| \"invalid_descriptor\"\n\t| \"invalid_metadata\"\n\t| \"invalid_artifact\"\n\t| \"source_mismatch\"\n\t| \"identity_mismatch\"\n\t| \"digest_mismatch\"\n\t| \"signature_invalid\"\n\t| \"expired\"\n\t| \"size_mismatch\"\n\t| \"media_type_mismatch\"\n\t| \"host_failed\"\n\t| \"release_failed\";\n\nconst ERROR_MESSAGES: Readonly<Record<PluginDistributionErrorCodeV1, string>> = {\n\tunsupported: \"Plugin distribution is unsupported on this host\",\n\tcancelled: \"Plugin distribution operation was cancelled\",\n\tinvalid_descriptor: \"Plugin distribution descriptor is invalid\",\n\tinvalid_metadata: \"Plugin distribution metadata is invalid\",\n\tinvalid_artifact: \"Plugin distribution artifact handle is invalid\",\n\tsource_mismatch: \"Plugin distribution source does not match the descriptor\",\n\tidentity_mismatch: \"Plugin distribution plugin identity does not match the descriptor\",\n\tdigest_mismatch: \"Plugin distribution digest does not match the descriptor\",\n\tsignature_invalid: \"Plugin distribution signature was rejected\",\n\texpired: \"Plugin distribution descriptor has expired\",\n\tsize_mismatch: \"Plugin distribution size does not match the descriptor\",\n\tmedia_type_mismatch: \"Plugin distribution media type does not match the descriptor\",\n\thost_failed: \"Plugin distribution host operation failed\",\n\trelease_failed: \"Plugin distribution artifact release failed\",\n};\n\n/** Stable, non-leaking distribution error. Host exception messages are never retained. */\nexport class PluginDistributionErrorV1 extends Error {\n\treadonly code: PluginDistributionErrorCodeV1;\n\n\tconstructor(code: PluginDistributionErrorCodeV1) {\n\t\tsuper(ERROR_MESSAGES[code]);\n\t\tthis.name = \"PluginDistributionErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\nexport interface PluginDistributionV1 {\n\t/** Validate and detach a descriptor before passing it to a host or verifier. */\n\tvalidateDescriptor(input: unknown): PluginDistributionDescriptorV1;\n\tresolveMetadata(input: { descriptor: unknown; signal?: AbortSignal }): Promise<PluginDistributionMetadataV1>;\n\tacquireArtifact(input: {\n\t\tdescriptor: unknown;\n\t\tmetadata?: unknown;\n\t\tsignal?: AbortSignal;\n\t}): Promise<PluginDistributionArtifactV1>;\n\treleaseArtifact(input: { artifact: unknown; signal?: AbortSignal }): Promise<void>;\n}\n\nconst DESCRIPTOR_KEYS = [\n\t\"version\",\n\t\"source\",\n\t\"pluginId\",\n\t\"pluginVersion\",\n\t\"manifestDigest\",\n\t\"artifactDigest\",\n\t\"signature\",\n\t\"expiresAt\",\n\t\"sizeBytes\",\n\t\"mediaType\",\n] as const;\nconst METADATA_KEYS = [\n\t\"version\",\n\t\"source\",\n\t\"pluginId\",\n\t\"pluginVersion\",\n\t\"manifestDigest\",\n\t\"artifactDigest\",\n\t\"expiresAt\",\n\t\"sizeBytes\",\n\t\"mediaType\",\n] as const;\nconst ARTIFACT_KEYS = [\"artifactRef\", \"artifactDigest\", \"sizeBytes\", \"mediaType\"] as const;\n\nfunction reject(code: PluginDistributionErrorCodeV1): never {\n\tthrow new PluginDistributionErrorV1(code);\n}\n\nfunction hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {\n\tconst expected = new Set(keys);\n\treturn (\n\t\tObject.keys(value).every((key) => expected.has(key) && expected.size === keys.length) &&\n\t\tkeys.every((key) => key in value)\n\t);\n}\n\nfunction boundedString(value: unknown, code: PluginDistributionErrorCodeV1): string {\n\tif (\n\t\ttypeof value !== \"string\" ||\n\t\tvalue.trim().length === 0 ||\n\t\tvalue.length > MAX_PLUGIN_DISTRIBUTION_FIELD_CHARS_V1 ||\n\t\t/[\\u0000-\\u001f\\u007f]/u.test(value)\n\t) {\n\t\treject(code);\n\t}\n\treturn value;\n}\n\nfunction identityString(value: unknown, code: PluginDistributionErrorCodeV1): string {\n\tconst result = boundedString(value, code);\n\tif (/\\s/u.test(result)) reject(code);\n\treturn result;\n}\n\nfunction sourceString(value: unknown, code: PluginDistributionErrorCodeV1): string {\n\tconst source = boundedString(value, code);\n\tif (/\\s/u.test(source) || /^(?:file:|[a-zA-Z]:[\\\\/]|[\\\\/]{1,2}|\\\\\\\\)/iu.test(source)) reject(code);\n\tif (/^https?:\\/\\//iu.test(source)) {\n\t\ttry {\n\t\t\tconst parsed = new URL(source);\n\t\t\tif (parsed.username !== \"\" || parsed.password !== \"\") {\n\t\t\t\tparsed.username = \"\";\n\t\t\t\tparsed.password = \"\";\n\t\t\t}\n\t\t\tparsed.search = \"\";\n\t\t\tparsed.hash = \"\";\n\t\t\tconst pathname = parsed.pathname.length > 512 ? `${parsed.pathname.slice(0, 509)}...` : parsed.pathname;\n\t\t\treturn `${parsed.origin}${pathname || \"/\"}`;\n\t\t} catch {\n\t\t\treject(code);\n\t\t}\n\t}\n\treturn source;\n}\n\nfunction digestString(value: unknown, code: PluginDistributionErrorCodeV1): string {\n\tconst digest = identityString(value, code);\n\t// Hosts may use a cryptographic digest or a versioned digest token. The\n\t// boundary validates shape and equality; only the host can verify bytes.\n\tif (!/^(?:[a-z][a-z0-9+.-]{0,15}:[A-Za-z0-9._~-]{1,128}|[0-9a-f]{16,128})$/u.test(digest)) reject(code);\n\treturn digest;\n}\n\nfunction signatureString(value: unknown): string {\n\tconst signature = boundedString(value, \"invalid_descriptor\");\n\tif (signature.length > 512 || /\\s/u.test(signature)) reject(\"invalid_descriptor\");\n\treturn signature;\n}\n\nfunction expiryString(value: unknown, code: PluginDistributionErrorCodeV1): string {\n\tconst expiry = boundedString(value, code);\n\tif (!/^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?Z$/u.test(expiry)) reject(code);\n\tconst timestamp = Date.parse(expiry);\n\tif (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== expiry) reject(code);\n\treturn expiry;\n}\n\nfunction positiveSize(value: unknown, code: PluginDistributionErrorCodeV1): number {\n\tif (\n\t\ttypeof value !== \"number\" ||\n\t\t!Number.isSafeInteger(value) ||\n\t\tvalue < 1 ||\n\t\tvalue > MAX_PLUGIN_DISTRIBUTION_ARTIFACT_BYTES_V1\n\t)\n\t\treject(code);\n\treturn value;\n}\n\nfunction mediaTypeString(value: unknown, code: PluginDistributionErrorCodeV1): string {\n\tconst mediaType = boundedString(value, code).toLowerCase();\n\tif (\n\t\tmediaType.length > 256 ||\n\t\t!/^[a-z0-9!#$&^_.+-]+\\/[a-z0-9!#$&^_.+-]+(?:\\s*;\\s*[a-z0-9!#$&^_.+-]+=[a-z0-9!#$&^_.+-]+)*$/u.test(mediaType)\n\t)\n\t\treject(code);\n\treturn mediaType;\n}\n\nfunction serializedBytes(value: unknown, code: PluginDistributionErrorCodeV1): number {\n\ttry {\n\t\tconst serialized = JSON.stringify(value);\n\t\tif (serialized === undefined) reject(code);\n\t\treturn new TextEncoder().encode(serialized).byteLength;\n\t} catch {\n\t\treject(code);\n\t}\n}\n\nfunction descriptorValue(value: unknown): PluginDistributionDescriptorV1 {\n\tif (!isPlainRecord(value) || !hasExactKeys(value, DESCRIPTOR_KEYS)) reject(\"invalid_descriptor\");\n\tif (value.version !== PLUGIN_DISTRIBUTION_CONTRACT_VERSION_V1) reject(\"invalid_descriptor\");\n\tconst descriptor = {\n\t\tversion: PLUGIN_DISTRIBUTION_CONTRACT_VERSION_V1,\n\t\tsource: sourceString(value.source, \"invalid_descriptor\"),\n\t\tpluginId: identityString(value.pluginId, \"invalid_descriptor\"),\n\t\tpluginVersion: identityString(value.pluginVersion, \"invalid_descriptor\"),\n\t\tmanifestDigest: digestString(value.manifestDigest, \"invalid_descriptor\"),\n\t\tartifactDigest: digestString(value.artifactDigest, \"invalid_descriptor\"),\n\t\tsignature: signatureString(value.signature),\n\t\texpiresAt: expiryString(value.expiresAt, \"invalid_descriptor\"),\n\t\tsizeBytes: positiveSize(value.sizeBytes, \"invalid_descriptor\"),\n\t\tmediaType: mediaTypeString(value.mediaType, \"invalid_descriptor\"),\n\t};\n\tif (serializedBytes(descriptor, \"invalid_descriptor\") > MAX_PLUGIN_DISTRIBUTION_DESCRIPTOR_BYTES_V1)\n\t\treject(\"invalid_descriptor\");\n\treturn detachedFreeze(descriptor);\n}\n\nfunction metadataValue(value: unknown): PluginDistributionMetadataV1 {\n\tif (!isPlainRecord(value) || !hasExactKeys(value, METADATA_KEYS)) reject(\"invalid_metadata\");\n\tif (value.version !== PLUGIN_DISTRIBUTION_CONTRACT_VERSION_V1) reject(\"invalid_metadata\");\n\tconst metadata = {\n\t\tversion: PLUGIN_DISTRIBUTION_CONTRACT_VERSION_V1,\n\t\tsource: sourceString(value.source, \"invalid_metadata\"),\n\t\tpluginId: identityString(value.pluginId, \"invalid_metadata\"),\n\t\tpluginVersion: identityString(value.pluginVersion, \"invalid_metadata\"),\n\t\tmanifestDigest: digestString(value.manifestDigest, \"invalid_metadata\"),\n\t\tartifactDigest: digestString(value.artifactDigest, \"invalid_metadata\"),\n\t\texpiresAt: expiryString(value.expiresAt, \"invalid_metadata\"),\n\t\tsizeBytes: positiveSize(value.sizeBytes, \"invalid_metadata\"),\n\t\tmediaType: mediaTypeString(value.mediaType, \"invalid_metadata\"),\n\t};\n\tif (serializedBytes(metadata, \"invalid_metadata\") > MAX_PLUGIN_DISTRIBUTION_METADATA_BYTES_V1)\n\t\treject(\"invalid_metadata\");\n\treturn detachedFreeze(metadata);\n}\n\nfunction artifactHandleValue(value: unknown): PluginDistributionArtifactHandleV1 {\n\tif (!isPlainRecord(value) || !hasExactKeys(value, ARTIFACT_KEYS)) reject(\"invalid_artifact\");\n\tconst artifact = {\n\t\tartifactRef: boundedString(value.artifactRef, \"invalid_artifact\"),\n\t\tartifactDigest: digestString(value.artifactDigest, \"invalid_artifact\"),\n\t\tsizeBytes: positiveSize(value.sizeBytes, \"invalid_artifact\"),\n\t\tmediaType: mediaTypeString(value.mediaType, \"invalid_artifact\"),\n\t};\n\tif (\n\t\t/[\\s\\u0000-\\u001f\\u007f]/u.test(artifact.artifactRef) ||\n\t\t/^(?:file:|[a-zA-Z]:[\\\\/]|[\\\\/]{1,2}|\\\\\\\\)/iu.test(artifact.artifactRef) ||\n\t\tartifact.artifactRef.length > MAX_PLUGIN_DISTRIBUTION_ARTIFACT_REF_CHARS_V1\n\t)\n\t\treject(\"invalid_artifact\");\n\treturn detachedFreeze(artifact);\n}\n\nfunction assertDescriptorMetadataMatch(\n\tdescriptor: PluginDistributionDescriptorV1,\n\tmetadata: PluginDistributionMetadataV1,\n): void {\n\tif (metadata.source !== descriptor.source) reject(\"source_mismatch\");\n\tif (metadata.pluginId !== descriptor.pluginId || metadata.pluginVersion !== descriptor.pluginVersion)\n\t\treject(\"identity_mismatch\");\n\tif (metadata.manifestDigest !== descriptor.manifestDigest || metadata.artifactDigest !== descriptor.artifactDigest)\n\t\treject(\"digest_mismatch\");\n\tif (metadata.expiresAt !== descriptor.expiresAt) reject(\"expired\");\n\tif (metadata.sizeBytes !== descriptor.sizeBytes) reject(\"size_mismatch\");\n\tif (metadata.mediaType !== descriptor.mediaType) reject(\"media_type_mismatch\");\n}\n\nfunction assertArtifactMatch(\n\tdescriptor: PluginDistributionDescriptorV1,\n\tartifact: PluginDistributionArtifactHandleV1,\n): void {\n\tif (artifact.artifactDigest !== descriptor.artifactDigest) reject(\"digest_mismatch\");\n\tif (artifact.sizeBytes !== descriptor.sizeBytes) reject(\"size_mismatch\");\n\tif (artifact.mediaType !== descriptor.mediaType) reject(\"media_type_mismatch\");\n}\n\nfunction isCancelled(error: unknown, signal: AbortSignal | undefined): boolean {\n\treturn (\n\t\tsignal?.aborted === true ||\n\t\t(error instanceof Error && (error.name === \"AbortError\" || error.name === \"AbortSignalError\"))\n\t);\n}\n\nfunction assertNotExpired(descriptor: PluginDistributionDescriptorV1, now: () => number): void {\n\tlet current: number;\n\ttry {\n\t\tcurrent = now();\n\t} catch {\n\t\treject(\"expired\");\n\t}\n\tif (!Number.isFinite(current)) reject(\"expired\");\n\tif (Date.parse(descriptor.expiresAt) <= current) reject(\"expired\");\n}\n\nasync function verifyDescriptor(\n\tdescriptor: PluginDistributionDescriptorV1,\n\tverifySignature: PluginDistributionSignatureVerifierV1 | undefined,\n\tnow: () => number,\n\tsignal: AbortSignal | undefined,\n): Promise<void> {\n\tif (signal?.aborted) reject(\"cancelled\");\n\tassertNotExpired(descriptor, now);\n\tif (verifySignature === undefined) reject(\"unsupported\");\n\tlet verification: PluginDistributionSignatureVerificationV1;\n\ttry {\n\t\tverification = await verifySignature({ descriptor });\n\t} catch {\n\t\treject(\"signature_invalid\");\n\t}\n\tif (signal?.aborted) reject(\"cancelled\");\n\tif (!isPlainRecord(verification) || verification.status !== \"accepted\") reject(\"signature_invalid\");\n}\n\n/** Create a host-injected distribution client. No host means all side effects are unsupported. */\nexport function createPluginDistributionV1(options: PluginDistributionOptionsV1 = {}): PluginDistributionV1 {\n\tconst verifySignature = options.verifySignature ?? options.verify;\n\tconst now = options.now ?? (() => Date.now());\n\tconst resolveMetadataForDescriptor = async (\n\t\tdescriptor: PluginDistributionDescriptorV1,\n\t\tsignal: AbortSignal | undefined,\n\t): Promise<PluginDistributionMetadataV1> => {\n\t\tif (signal?.aborted) reject(\"cancelled\");\n\t\tif (options.host?.resolveMetadata === undefined) reject(\"unsupported\");\n\t\tlet result: PluginDistributionMetadataV1;\n\t\ttry {\n\t\t\tresult = await options.host.resolveMetadata({ descriptor, signal });\n\t\t} catch (error) {\n\t\t\tif (isCancelled(error, signal)) reject(\"cancelled\");\n\t\t\treject(\"host_failed\");\n\t\t}\n\t\tif (signal?.aborted) reject(\"cancelled\");\n\t\tconst metadata = metadataValue(result);\n\t\tassertDescriptorMetadataMatch(descriptor, metadata);\n\t\tassertNotExpired(descriptor, now);\n\t\treturn metadata;\n\t};\n\n\tconst resolveMetadata = async (input: {\n\t\tdescriptor: unknown;\n\t\tsignal?: AbortSignal;\n\t}): Promise<PluginDistributionMetadataV1> => {\n\t\tconst descriptor = descriptorValue(input.descriptor);\n\t\tawait verifyDescriptor(descriptor, verifySignature, now, input.signal);\n\t\treturn resolveMetadataForDescriptor(descriptor, input.signal);\n\t};\n\n\tconst acquireArtifact = async (input: {\n\t\tdescriptor: unknown;\n\t\tmetadata?: unknown;\n\t\tsignal?: AbortSignal;\n\t}): Promise<PluginDistributionArtifactV1> => {\n\t\tconst descriptor = descriptorValue(input.descriptor);\n\t\tawait verifyDescriptor(descriptor, verifySignature, now, input.signal);\n\t\tif (options.host?.acquireArtifact === undefined) reject(\"unsupported\");\n\t\tconst metadata =\n\t\t\tinput.metadata === undefined\n\t\t\t\t? await resolveMetadataForDescriptor(descriptor, input.signal)\n\t\t\t\t: metadataValue(input.metadata);\n\t\tassertDescriptorMetadataMatch(descriptor, metadata);\n\t\tassertNotExpired(descriptor, now);\n\t\tlet result: PluginDistributionArtifactHandleV1;\n\t\tlet acquired: PluginDistributionArtifactV1 | undefined;\n\t\ttry {\n\t\t\tresult = await options.host.acquireArtifact({ descriptor, metadata, signal: input.signal });\n\t\t\tconst handle = artifactHandleValue(result);\n\t\t\tacquired = detachedFreeze({ ...metadata, artifactRef: handle.artifactRef });\n\t\t\tassertArtifactMatch(descriptor, handle);\n\t\t\tassertNotExpired(descriptor, now);\n\t\t\tif (input.signal?.aborted) reject(\"cancelled\");\n\t\t\treturn acquired;\n\t\t} catch (error) {\n\t\t\tif (acquired !== undefined && options.host.releaseArtifact !== undefined) {\n\t\t\t\tawait options.host.releaseArtifact({ artifact: acquired }).catch(() => undefined);\n\t\t\t}\n\t\t\tif (error instanceof PluginDistributionErrorV1) throw error;\n\t\t\tif (isCancelled(error, input.signal)) reject(\"cancelled\");\n\t\t\treject(\"host_failed\");\n\t\t}\n\t};\n\n\tconst releaseArtifact = async (input: { artifact: unknown; signal?: AbortSignal }): Promise<void> => {\n\t\tif (input.signal?.aborted) reject(\"cancelled\");\n\t\tif (options.host?.releaseArtifact === undefined) reject(\"unsupported\");\n\t\tconst value = input.artifact;\n\t\tif (!isPlainRecord(value) || !hasExactKeys(value, [...METADATA_KEYS, \"artifactRef\"])) reject(\"invalid_artifact\");\n\t\tconst metadataInput = Object.fromEntries(METADATA_KEYS.map((key) => [key, value[key]]));\n\t\tconst artifact = {\n\t\t\t...metadataValue(metadataInput),\n\t\t\tartifactRef: artifactHandleValue({\n\t\t\t\tartifactRef: value.artifactRef,\n\t\t\t\tartifactDigest: value.artifactDigest,\n\t\t\t\tsizeBytes: value.sizeBytes,\n\t\t\t\tmediaType: value.mediaType,\n\t\t\t}).artifactRef,\n\t\t};\n\t\ttry {\n\t\t\tawait options.host.releaseArtifact({ artifact: detachedFreeze(artifact), signal: input.signal });\n\t\t} catch (error) {\n\t\t\tif (isCancelled(error, input.signal)) reject(\"cancelled\");\n\t\t\treject(\"release_failed\");\n\t\t}\n\t\tif (input.signal?.aborted) reject(\"cancelled\");\n\t};\n\n\treturn {\n\t\tvalidateDescriptor(input) {\n\t\t\treturn descriptorValue(input);\n\t\t},\n\t\tresolveMetadata,\n\t\tacquireArtifact,\n\t\treleaseArtifact,\n\t};\n}\n"]}