feat(studio): load external artifact provider modules

Implement docs/specs/2026-08-25-external-artifact-provider-modules.md by loading explicit operator-provisioned factories through the existing receipt and activation boundary. Validated with Node 24 Studio build, 270 unit tests, focused module tests, hosted Playwright, and the Homology cross-repository browser E2E.

Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

Author: phodal

docs/specs/2026-08-25-external-artifact-provider-modules.md

@@ -0,0 +1,59 @@
+# External Artifact provider modules
+
+## Traceability
+
+- Spec ID: external-artifact-provider-modules
+- Status: Implemented
+
+## Intent
+
+Let an operator run a separately published Artifact Provider in Harness Studio
+without copying its renderer or adapter into Studio. The host owns module
+loading and Provider validation; the external package owns format semantics and
+its receipt-bound implementation.
+
+## Acceptance Scenarios
+
+- AC-1: Repeated `--artifact-provider-module <specifier>` options load the
+  module's `createArtifactProvider()` result and inject it through Studio's
+  existing external Provider registry.
+- AC-2: Relative module paths resolve from `--cwd`, package specifiers resolve
+  through Node, and URL/builtin/empty/duplicate/over-budget inputs fail before
+  Studio opens a port.
+- AC-3: A real published Homology Notebook Provider can be activated and render
+  an `.ipynb` through the generic hosted surface; Studio does not import the
+  Provider's private renderer or adapter files.
+- AC-4: Help, TypeScript build, focused unit/server tests, and a clean packed
+  cross-repository consumer prove the integration boundary.
+
+## Non-goals
+
+- Downloading or installing Provider packages from the Studio UI.
+- Granting an untrusted module a sandbox; module loading is an explicit
+  operator-authorized local-code action.
+- Moving Notebook or kernel execution semantics into Better Harness.
+- Automatically activating a contribution without the existing fingerprint-
+  bound activation record.
+
+## Plan and Tasks
+
+- Add a bounded Node module loader beside Artifact Provider discovery.
+- Add a repeatable CLI option and pass loaded Providers through the existing
+  `artifactProviders` embedding seam.
+- Declare the Homology Provider as an optional peer integration after it has a
+  public npm identity; keep Studio independently runnable without it.
+- Test parsing, path/package resolution, failure closure, registry status, and
+  the real cross-repository package lane.
+
+## Test and Review Evidence
+
+- AC-1/AC-2: focused Vitest for loader and CLI behavior.
+- AC-3: Homology clean-consumer tarballs plus Harness Studio server/browser E2E.
+- AC-4: Node 24 package build/test/pack and Review Readiness Check.
+- Risk: loaded modules execute with the Studio process authority. The CLI help
+  and spec identify this as an operator-provisioned local-code boundary; no
+  browser-controlled module specifier is accepted.
+- Implemented evidence: Node 24 Studio build and 46 files/270 Vitest tests;
+  generic external-host Playwright 1/1; Homology's packed-provider browser E2E
+  loaded the public factory, verified/activated its receipt, rendered Markdown
+  plus stored output, and reported 0 console/page errors.

package-lock.json

@@ -103,6 +103,20 @@ are part of build/cache identity. They do not expand the package allowlist.
 Injected Provider receipts are fingerprint-checked, and an inactive or changed
 fingerprint never enters selection.
 
+The standalone CLI accepts the same boundary without importing Provider-private
+files. Install the Provider beside Studio, then name its public module
+explicitly (loading it executes trusted local code):
+
+```bash
+harness-studio \
+  --artifact-provider-module @homology/integration-harness-notebook-provider \
+  --artifacts ./artifacts
+```
+
+The module must export `createArtifactProvider()`. Contributions remain inactive
+until `harness-studio artifact-provider activate` records the exact Provider
+fingerprint and matcher.
+
 ## Architecture
 
 ```text

packages/harness-studio/README.md

@@ -61,6 +61,14 @@
     "react-arborist": "^3.16.0",
     "react-dom": "19.2.8"
   },
+  "peerDependencies": {
+    "@homology/integration-harness-notebook-provider": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@homology/integration-harness-notebook-provider": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@playwright/test": "^1.62.1",
     "@types/node": "26.2.0",

packages/harness-studio/package.json

@@ -46,3 +46,7 @@ export {
   resolveArtifactCompileLimits,
   type ArtifactCompileLimits,
 } from "./server/artifacts/registry/artifact-compile-runtime.js";
+export {
+  loadArtifactProviderModules,
+  providerModuleTarget,
+} from "./server/artifacts/registry/artifact-provider-modules.js";

packages/harness-studio/src/index.ts

@@ -0,0 +1,54 @@
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { ExternalArtifactProvider } from "../../../contracts/artifact.js";
+
+const MAX_PROVIDER_MODULES = 16;
+const PACKAGE_SPECIFIER = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/u;
+
+interface ArtifactProviderModule {
+  readonly createArtifactProvider?: () => ExternalArtifactProvider | Promise<ExternalArtifactProvider>;
+}
+
+/** Load explicit operator-provisioned modules before Studio opens a port. */
+export async function loadArtifactProviderModules(
+  specifiers: readonly string[],
+  cwd: string,
+): Promise<readonly ExternalArtifactProvider[]> {
+  if (specifiers.length > MAX_PROVIDER_MODULES) {
+    throw new Error(`At most ${MAX_PROVIDER_MODULES} Artifact Provider modules may be loaded.`);
+  }
+  const seen = new Set<string>();
+  const providers: ExternalArtifactProvider[] = [];
+  for (const specifier of specifiers) {
+    const target = providerModuleTarget(specifier, cwd);
+    if (seen.has(target)) throw new Error(`Artifact Provider module '${specifier}' was supplied more than once.`);
+    seen.add(target);
+    const loaded: unknown = await import(target);
+    if (loaded === null || typeof loaded !== "object") {
+      throw new Error(`Artifact Provider module '${specifier}' has no module exports.`);
+    }
+    const factory = (loaded as ArtifactProviderModule).createArtifactProvider;
+    if (typeof factory !== "function") {
+      throw new Error(`Artifact Provider module '${specifier}' must export createArtifactProvider().`);
+    }
+    const provider = await factory();
+    if (provider === null || typeof provider !== "object") {
+      throw new Error(`Artifact Provider module '${specifier}' returned an invalid Provider.`);
+    }
+    providers.push(provider);
+  }
+  return Object.freeze(providers);
+}
+
+export function providerModuleTarget(specifier: string, cwd: string): string {
+  if (specifier.trim() !== specifier || specifier.length === 0) {
+    throw new Error("Artifact Provider module specifiers must be non-empty and contain no surrounding whitespace.");
+  }
+  if (specifier.startsWith(".") || isAbsolute(specifier)) {
+    return pathToFileURL(resolve(cwd, specifier)).href;
+  }
+  if (!PACKAGE_SPECIFIER.test(specifier)) {
+    throw new Error(`Artifact Provider module '${specifier}' must be a package name or filesystem path.`);
+  }
+  return specifier;
+}

packages/harness-studio/src/server/artifacts/registry/artifact-provider-modules.ts

@@ -7,6 +7,7 @@ import { readSourceCatalogFile } from "./workspace/source-catalog.js";
 import { runWalnutBootstrapCli } from "./providers/walnut/cli.js";
 import { runArtifactProviderCli } from "./artifacts/registry/artifact-provider-cli.js";
 import { createBundledAgentCustomizationCollector } from "./customization-collector.js";
+import { loadArtifactProviderModules } from "./artifacts/registry/artifact-provider-modules.js";
 
 const HELP = `harness-studio — local studio for harness runs and compare evidence
 
@@ -39,6 +40,9 @@ Options:
                       Prebuilt Canvas SDK media directory
   --provider-state <dir>
                       Studio-private external provider activation state
+  --artifact-provider-module <specifier>
+                      Repeatable operator-provisioned module exporting
+                      createArtifactProvider() (executes trusted local code)
   --walnut-cache <dir> Studio-owned Walnut cache root
   --source-catalog <file>
                       JSON catalog of bounded switchable Studio inputs
@@ -99,6 +103,7 @@ interface ParsedArgs {
   canvasSdkRoot?: string;
   canvasSdkMedia?: string;
   providerState?: string;
+  artifactProviderModules: string[];
   walnutCache?: string;
   sourceCatalog?: string;
   port: number;
@@ -111,7 +116,14 @@ interface ParsedArgs {
 }
 
 export function parseHarnessStudioArgs(argv: string[]): ParsedArgs {
-  const parsed: ParsedArgs = { port: 3311, host: "127.0.0.1", allowRemote: false, help: false, acpArgs: [] };
+  const parsed: ParsedArgs = {
+    port: 3311,
+    host: "127.0.0.1",
+    allowRemote: false,
+    help: false,
+    acpArgs: [],
+    artifactProviderModules: [],
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     const takeValue = (): string | undefined => {
@@ -176,6 +188,12 @@ export function parseHarnessStudioArgs(argv: string[]): ParsedArgs {
       case "--provider-state":
         parsed.providerState = takeValue();
         break;
+      case "--artifact-provider-module": {
+        const value = takeValue();
+        if (value === undefined) parsed.error = "--artifact-provider-module requires a package name or filesystem path.";
+        else parsed.artifactProviderModules.push(value);
+        break;
+      }
       case "--walnut-cache":
         parsed.walnutCache = takeValue();
         break;
@@ -243,6 +261,16 @@ export async function runHarnessStudioCli(argv: string[], io: HarnessStudioCliIo
   // Skills are conventionally declared relative to their `.harness` file (see
   // examples/*.harness), so loading one without a flag still delivers them.
   const sourceRoot = resolveHarnessStudioSourceRoot(parsed.harness, parsed.sourceRoot);
+  let artifactProviders;
+  try {
+    artifactProviders = await loadArtifactProviderModules(
+      parsed.artifactProviderModules,
+      resolve(parsed.cwd ?? process.cwd()),
+    );
+  } catch (error) {
+    io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 2;
+  }
   const started = await startHarnessStudioServer({
     appDir: defaultAppDir(),
     port: parsed.port,
@@ -269,6 +297,7 @@ export async function runHarnessStudioCli(argv: string[], io: HarnessStudioCliIo
     ...(parsed.canvasSdkRoot !== undefined ? { canvasSdkRoot: resolve(parsed.canvasSdkRoot) } : {}),
     ...(parsed.canvasSdkMedia !== undefined ? { canvasSdkMedia: resolve(parsed.canvasSdkMedia) } : {}),
     ...(parsed.providerState !== undefined ? { artifactProviderStateRoot: resolve(parsed.providerState) } : {}),
+    ...(artifactProviders.length > 0 ? { artifactProviders } : {}),
     ...(parsed.walnutCache !== undefined ? { walnutCacheRoot: resolve(parsed.walnutCache) } : {}),
     ...(sourceCatalog.length > 0 ? { sourceCatalog } : {}),
     ...(parsed.cwd !== undefined ? { cwd: parsed.cwd } : {}),

packages/harness-studio/src/server/cli.ts

@@ -0,0 +1,49 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  loadArtifactProviderModules,
+  providerModuleTarget,
+} from "../src/server/artifacts/registry/artifact-provider-modules.js";
+
+const temporary: string[] = [];
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map(async (path) => await rm(path, { recursive: true, force: true })));
+});
+
+describe("Artifact Provider modules", () => {
+  it("loads a relative operator-provisioned module through its canonical factory", async () => {
+    const root = await mkdtemp(join(tmpdir(), "artifact-provider-module-"));
+    temporary.push(root);
+    await mkdir(join(root, "providers"));
+    await writeFile(join(root, "providers", "fixture.mjs"), `
+export async function createArtifactProvider() {
+  return { id: "fixture.module", version: "1.0.0", label: "Fixture", contributions: [] };
+}
+`, "utf8");
+    const providers = await loadArtifactProviderModules(["./providers/fixture.mjs"], root);
+    expect(providers).toEqual([expect.objectContaining({ id: "fixture.module", version: "1.0.0" })]);
+    expect(Object.isFrozen(providers)).toBe(true);
+  });
+
+  it("accepts bounded package names and rejects implicit URL, builtin, duplicate, and over-budget loading", async () => {
+    expect(providerModuleTarget("@homology/integration-harness-notebook-provider", "/workspace")).toBe(
+      "@homology/integration-harness-notebook-provider",
+    );
+    expect(() => providerModuleTarget("node:fs", "/workspace")).toThrow("package name or filesystem path");
+    expect(() => providerModuleTarget("https://example.com/provider.mjs", "/workspace")).toThrow("package name or filesystem path");
+    const root = await mkdtemp(join(tmpdir(), "artifact-provider-duplicate-"));
+    temporary.push(root);
+    await writeFile(join(root, "fixture.mjs"), "export const createArtifactProvider = () => ({});", "utf8");
+    await expect(loadArtifactProviderModules(["./fixture.mjs", "./fixture.mjs"], root)).rejects.toThrow("more than once");
+    await expect(loadArtifactProviderModules(Array.from({ length: 17 }, (_, index) => `provider-${index}`), root)).rejects.toThrow("At most 16");
+  });
+
+  it("fails closed when the canonical factory is missing", async () => {
+    const root = await mkdtemp(join(tmpdir(), "artifact-provider-missing-factory-"));
+    temporary.push(root);
+    await writeFile(join(root, "fixture.mjs"), "export const value = 1;", "utf8");
+    await expect(loadArtifactProviderModules(["./fixture.mjs"], root)).rejects.toThrow("createArtifactProvider");
+  });
+});

packages/harness-studio/test/artifact-provider-modules.test.ts

@@ -1311,6 +1311,19 @@ describe("harness-studio CLI", () => {
     expect(parseHarnessStudioArgs([]).error).toBeUndefined();
   });
 
+  it("parses repeated operator-provisioned Artifact Provider modules", () => {
+    expect(parseHarnessStudioArgs([
+      "--artifact-provider-module", "@homology/integration-harness-notebook-provider",
+      "--artifact-provider-module", "./providers/local.mjs",
+    ]).artifactProviderModules).toEqual([
+      "@homology/integration-harness-notebook-provider",
+      "./providers/local.mjs",
+    ]);
+    expect(parseHarnessStudioArgs(["--artifact-provider-module"]).error).toBe(
+      "--artifact-provider-module requires a package name or filesystem path.",
+    );
+  });
+
   it("resolves the default source root from the harness file and honors an override", () => {
     expect(resolveHarnessStudioSourceRoot("/workspace/harnesses/agent.harness")).toBe(
       resolve("/workspace/harnesses"),