@mokuyoaxis/dsh-iris 0.3.0-alpha.1 → 0.3.0-beta.1

package/templates/provider-starter/README.md

@@ -0,0 +1,50 @@
+# Wan Provider starter / 万相供应商模板
+
+A copyable, independent Provider plugin using only `@mokuyoaxis/dsh-iris/plugins` and the public `package.json` export to locate the CLI. It implements the Wan 2.6 asynchronous image protocol itself. It does not call Iris's private transports or duplicate its Task store, queue, authentication or MCP server.
+
+This template requires **Core 0.3.0-beta.1 and Provider factory context v1**. It checks `PROVIDER_FACTORY_CONTEXT_VERSION === 1` before setup. Install the exact beta package or a verified compatible Core archive. The older alpha.1 package fails with an explicit feature error and creates no data.
+
+## Copy and check
+
+Copy this entire directory outside the Iris repository into a new project, then install the explicitly chosen Core archive in that project:
+
+```bash
+npm install --save-exact @mokuyoaxis/dsh-iris@0.3.0-beta.1
+node scripts/protocol-smoke.mjs
+npm test
+```
+
+These tests use synthetic credentials and loopback HTTP services only. They initialize new private temporary roots, run the actual installed Core CLI and formal HTTP MCP, and preserve their evidence directories. No provider account, paid call or harness configuration is involved. Archive acceptance separately checks the same template as its own npm tarball. The template has no runtime dependency beyond its Core peer and Node 22.1.0+.
+
+`private: true` prevents accidentally publishing this example. Before publishing your own plugin, choose your package/plugin/contribution IDs, review its implementation and compatibility, update its independent versions, then deliberately remove that flag. The local `npm pack --ignore-scripts` acceptance does not publish anything.
+
+## Configure a new workspace
+
+Provide the correct workspace/region API **root** from your own account. Do not append `/api/v1` or `/compatible-mode/v1`. Export your credential through your normal secure environment mechanism before starting Core; do not paste the key into a command argument or this project. Setup receives only the environment variable's **name**:
+
+```bash
+npm run setup -- \
+  --directory /absolute/path/to/new-private-wan-workspace \
+  --endpoint https://YOUR-WORKSPACE-API-ROOT \
+  --credential-env YOUR_WAN_KEY_VARIABLE
+```
+
+The parent directory must already exist. Setup refuses any existing target, even an empty directory, and refuses data inside the plugin project. It writes private Provider/startup files, initializes a new image-generation execution root through the public CLI, and prints exact `startArgv`. It never reads the key, starts a server, imports another harness's settings or submits a generation. Failed setup leaves its partial directory for inspection.
+
+Run the printed argv to open Core Web. The default Web login uses Core's normal first-use access passphrase flow. The contributed protocol appears in Provider settings. Read its actual model directory, review the result, explicitly save the supported model and select its image-generation policy. Setup leaves the model list empty and image generation disabled until that selection. Discovering a directory grants no execution authority.
+
+In Connections, select **image generation** and the required read/create/execute/stop permissions, then export the ordinary MCP configuration for your client. This Provider reuses the Core image tools; installing it does not add an independent MCP tool or grant a connection new rights. Core owns execution and artifacts. Keep the plugin installed at the configured path and its version unchanged while recovering its original tasks.
+
+## Supported protocol and limits
+
+- Identity: `example.wan-image` 0.1.0, contribution `example.wan-image.images` 0.1.0; Plugin/Adapter contract v0 plus factory context v1. Rename these together for your own implementation.
+- `GET /api/v1/models?capabilities=IG&page_no=…&page_size=100`: validate a complete, stable directory of at most 1,000 rows, then expose only actually returned `wan2.6-t2i`. A recognized ID is an implementation boundary, not a fabricated model pool or proof of account availability.
+- `POST /api/v1/services/aigc/image-generation/generation`: `X-DashScope-Async: enable`, `messages` text input, explicit `n` defaulting to 1, optional `width*height`. This is the Wan 2.6 format, not the older Wan 2.5 endpoint. Core's image Run currently requests one image; the adapter accepts 1–4 for other public consumers.
+- Poll only the original `/api/v1/tasks/{task_id}`. Missing submission identity or malformed/oversized submission responses mean **unknown acceptance**. Never retry a POST or switch a model/exit automatically after an ambiguous submission.
+- Download PNG results, at most 8 MiB each, into the exact new staging path supplied by Core. API requests refuse redirects; signed CDN downloads follow redirects through the same borrowed Core network port and receive no API Authorization header. JSON responses are limited to 1 MiB. Upstream details are not reflected into safe errors.
+- No source upload, image edit, remote cancellation or unsupported model fallback. Stopping local waiting does not prove remote cancellation or stopped billing. Remote task IDs/result URLs have the vendor's limited lifetime; persistence cannot recover a vendor-expired result.
+- The adapter owns no agents, background timers or queues. Core resolves the current credential for each factory, owns network routing/scheduling, and drains each full awaited method, including body reads and child requests. Await every request and body before returning; do not keep the borrowed port for later background work or dispose it.
+
+The plugin is trusted Node code, not a network/filesystem sandbox. This reference intentionally uses only the borrowed `context.network.fetch` for its HTTP requests and writes only the supplied delivery file.
+
+The protocol was checked against the official [Wan image API](https://help.aliyun.com/zh/model-studio/text-to-image-v2-api-reference) and [model directory API](https://help.aliyun.com/zh/model-studio/list-models) on 2026-11-03. Acceptance uses controlled local responses; it does not certify a live account, region, billing behavior or every Wan model.

package/templates/provider-starter/index.d.mts

@@ -0,0 +1,5 @@
+import type { CorePlugin } from '@mokuyoaxis/dsh-iris/plugins';
+export const PROVIDER_PROTOCOL: 'example.wan-image.images';
+export const SUPPORTED_MODEL: 'wan2.6-t2i';
+declare const plugin: CorePlugin;
+export default plugin;

package/templates/provider-starter/index.mjs

@@ -0,0 +1,165 @@
+import * as iris from '@mokuyoaxis/dsh-iris/plugins';
+import { writeFileSync } from 'node:fs';
+
+if (iris.PROVIDER_FACTORY_CONTEXT_VERSION !== 1 || typeof iris.ProviderContractError !== 'function') {
+  throw new Error('Wan Provider starter requires Iris Provider factory context v1. Published 0.3.0-alpha.1 does not include it; use the verified newer Core candidate described in README.');
+}
+const { definePlugin, defineProviderAdapter, ProviderContractError, normalizeMediaEndpoint } = iris;
+export const PROVIDER_PROTOCOL = 'example.wan-image.images';
+export const SUPPORTED_MODEL = 'wan2.6-t2i';
+const JSON_LIMIT = 1024 * 1024, IMAGE_LIMIT = 8 * 1024 * 1024, DIRECTORY_LIMIT = 1000;
+
+function failure(message, stage, acceptance, category = 'protocol', details = {}) {
+  return new ProviderContractError(message, { stage, acceptance, category, ...details });
+}
+function endpoint(value) {
+  const base = normalizeMediaEndpoint(value);
+  if (/\/(?:api\/v1|compatible-mode\/v1)$/.test(new URL(base).pathname)) {
+    throw failure('Use the workspace API root, without /api/v1 or /compatible-mode/v1.', 'validate', 'not_accepted', 'invalid_request');
+  }
+  return base;
+}
+function boundedSignal(request) {
+  const deadline = AbortSignal.timeout(request.timeoutMs ?? 30000);
+  return request.signal ? AbortSignal.any([request.signal, deadline]) : deadline;
+}
+async function readBody(response, limit, stage, acceptance) {
+  if (!response.body) throw failure('Response has no body.', stage, acceptance);
+  const reader = response.body.getReader(), chunks = []; let size = 0;
+  try {
+    for (;;) {
+      const item = await reader.read(); if (item.done) break;
+      size += item.value.byteLength;
+      if (size > limit) {
+        await reader.cancel(); throw failure('Response exceeds the documented starter size limit.', stage, acceptance);
+      }
+      chunks.push(Buffer.from(item.value));
+    }
+    return Buffer.concat(chunks, size);
+  } finally { reader.releaseLock(); }
+}
+function json(bytes, stage, acceptance) {
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { throw failure('Provider response is not valid UTF-8 JSON.', stage, acceptance); }
+}
+function httpFailure(response, operation) {
+  const ambiguous = [408, 409, 425, 499].includes(response.status);
+  const known = operation === 'submit' && response.status >= 400 && response.status < 500 && !ambiguous;
+  const acceptance = operation === 'submit' ? known ? 'not_accepted' : 'unknown' : operation === 'discover' ? 'not_accepted' : 'accepted';
+  const category = [401, 403].includes(response.status) ? 'authentication' : response.status === 429 ? 'rate_limit' : response.status >= 500 ? 'provider' : 'invalid_request';
+  const error = failure(`Wan HTTP request failed (${response.status}).`, operation === 'discover' ? 'validate' : operation, acceptance, category,
+    { httpStatus: response.status, retryable: response.status === 429 || response.status >= 500 });
+  if (response.status === 429) {
+    const value = response.headers.get('retry-after'), seconds = value && Number(value), date = value && Date.parse(value);
+    if (Number.isFinite(seconds) && seconds >= 0) error.retryAfterMs = Math.max(1000, seconds * 1000);
+    else if (Number.isFinite(date) && date > Date.now()) error.retryAfterMs = date - Date.now();
+  }
+  return error;
+}
+
+export default definePlugin({
+  manifest: { contractVersion: 0, id: 'example.wan-image', version: '0.1.0',
+    compatibility: { min: '0.3.0-alpha.1', maxExclusive: '0.4.0' },
+    contributions: { providers: [{ id: 'images', version: '0.1.0', title: 'Wan 2.6 async image reference', capabilities: ['image-gen'],
+      configuration: [{ key: 'baseUrl', type: 'url', label: 'Workspace API root', required: true },
+        { key: 'mediaBaseUrl', type: 'url', label: 'Separate media API root', advanced: true },
+        { key: 'apiKey', type: 'secret', label: 'API key', required: true }] }] } },
+  activate() {
+    // No timers, agents or global state to close. Core owns the borrowed network port.
+    return { providers: { images: { normalizeEndpoint: endpoint,
+      supportsModel: ({ modelId, capability }) => modelId === SUPPORTED_MODEL && capability === 'image-gen',
+      supportsImageEdit: () => false,
+      createAdapter(provider, context) {
+        if (context?.contractVersion !== 1 || typeof context.network?.fetch !== 'function') {
+          throw failure('Core must supply Provider factory context v1.', 'validate', 'not_accepted', 'invalid_request');
+        }
+        const base = endpoint(provider.mediaBaseUrl || provider.baseUrl), key = provider.apiKey || '';
+        if (provider.auth !== 'none' && !key) throw failure('Configure an API credential in Core before calling this Provider.', 'validate', 'not_accepted', 'authentication');
+        const headers = { 'Content-Type': 'application/json', ...(key ? { Authorization: 'Bearer ' + key } : {}) };
+        async function api(route, request, operation, payload) {
+          const response = await context.network.fetch(base + route, { method: payload === undefined ? 'GET' : 'POST',
+            redirect: 'error', signal: boundedSignal(request), headers: { ...headers, ...(operation === 'submit' ? { 'X-DashScope-Async': 'enable' } : {}) },
+            ...(payload === undefined ? {} : { body: JSON.stringify(payload) }) });
+          const acceptance = operation === 'submit' ? 'unknown' : operation === 'discover' ? 'not_accepted' : 'accepted';
+          const stage = operation === 'discover' ? 'validate' : operation === 'submit' ? 'response' : operation;
+          const bytes = await readBody(response, JSON_LIMIT, stage, acceptance);
+          if (!response.ok) throw httpFailure(response, operation);
+          return json(bytes, stage, acceptance);
+        }
+        return defineProviderAdapter({ id: provider.id, protocol: PROVIDER_PROTOCOL, capabilities: ['image'], operations: {
+          async discover(request = {}) {
+            const models = [], seen = new Set(); let total;
+            for (let page = 1; page <= 10; page++) {
+              const value = await api(`/api/v1/models?capabilities=IG&page_no=${page}&page_size=100`, request, 'discover');
+              const output = value?.output;
+              if (!output || !Array.isArray(output.models) || output.models.length > 100 || !Number.isSafeInteger(output.total)
+                  || output.total < 0 || output.total > DIRECTORY_LIMIT || output.page_no !== page || output.page_size !== 100
+                  || total !== undefined && total !== output.total) throw failure('Model directory pagination is invalid or changed; keep the previous complete snapshot.', 'validate', 'not_accepted');
+              total = output.total;
+              for (const model of output.models) {
+                if (!model || typeof model.model !== 'string' || !model.model || seen.has(model.model)) throw failure('Model directory contains invalid or duplicate IDs.', 'validate', 'not_accepted');
+                seen.add(model.model);
+                if (model.model === SUPPORTED_MODEL) models.push({ id: model.model, capabilities: ['image-gen'] });
+              }
+              if (seen.size === total) return { models };
+              if (!output.models.length || seen.size > total) throw failure('Model directory is incomplete.', 'validate', 'not_accepted');
+            }
+            throw failure('Model directory exceeded the bounded page count.', 'validate', 'not_accepted');
+          },
+          async submit(request) {
+            const { input } = request;
+            if (request.capability !== 'image' || request.model !== SUPPORTED_MODEL || input.image !== undefined) {
+              throw failure('This reference supports only Wan 2.6 text-to-image; image editing and other models are unsupported.', 'validate', 'not_accepted', 'invalid_request');
+            }
+            if (typeof input.prompt !== 'string' || !input.prompt.trim() || Array.from(input.prompt).length > 2100
+                || input.n !== undefined && (!Number.isSafeInteger(input.n) || input.n < 1 || input.n > 4)
+                || input.size !== undefined && (typeof input.size !== 'string' || !/^\d+[x*]\d+$/i.test(input.size))) {
+              throw failure('Use a nonempty prompt of at most 2100 characters, n=1–4 and an optional width*height size.', 'validate', 'not_accepted', 'invalid_request');
+            }
+            const value = await api('/api/v1/services/aigc/image-generation/generation', request, 'submit', { model: request.model,
+              input: { messages: [{ role: 'user', content: [{ text: input.prompt }] }] },
+              parameters: { n: input.n ?? 1, ...(input.size ? { size: input.size.replace(/x/i, '*') } : {}) } });
+            if (typeof value?.output?.task_id !== 'string' || !value.output.task_id.trim()) throw failure('Submission response has no remote task ID; acceptance remains unknown.', 'response', 'unknown');
+            return { kind: 'accepted', remoteTaskId: value.output.task_id };
+          },
+          async poll(request) {
+            const value = await api('/api/v1/tasks/' + encodeURIComponent(request.remoteTaskId), request, 'poll'), output = value?.output;
+            if (['PENDING', 'RUNNING'].includes(output?.task_status)) return { kind: 'pending', progress: output.task_status };
+            if (output?.task_status === 'SUCCEEDED') {
+              if (!Array.isArray(output.choices) || output.choices.some(choice => !Array.isArray(choice?.message?.content)
+                  || choice.message.content.some(item => !item || typeof item !== 'object'))) {
+                throw failure('Successful task response contains malformed image choices.', 'poll', 'accepted');
+              }
+              const images = output.choices.flatMap(choice => choice.message.content).flatMap(item => typeof item.image === 'string' && item.image ? [item.image] : []);
+              if (!images?.length || images.length > 4) throw failure('Successful task response has no usable image results.', 'poll', 'accepted');
+              return { kind: 'succeeded', artifacts: images.map(url => ({ kind: 'remote-url', url, mediaType: 'image/png' })) };
+            }
+            const kind = { FAILED: 'failed', CANCELED: 'canceled', UNKNOWN: 'unknown' }[output?.task_status];
+            if (kind) return { kind, error: failure('Remote task is ' + kind + '.', 'poll', 'accepted', kind === 'canceled' ? 'aborted' : kind === 'unknown' ? 'unknown' : 'provider') };
+            throw failure('Remote task response has an unrecognized status.', 'poll', 'accepted');
+          },
+          async download(request) {
+            if (request.artifact.kind !== 'remote-url') throw failure('Wan result must be a remote image URL.', 'download', 'accepted');
+            const url = new URL(request.artifact.url);
+            if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw failure('Result URL must use HTTP(S) without embedded credentials.', 'download', 'accepted');
+            // Presigned CDN URLs never receive the API Authorization header. Redirects use the same Core port.
+            const response = await context.network.fetch(url, { signal: boundedSignal(request) });
+            const bytes = await readBody(response, IMAGE_LIMIT, 'download', 'accepted');
+            if (!response.ok) throw httpFailure(response, 'download');
+            writeFileSync(request.targetPath, bytes, { mode: 0o600, flag: 'wx' });
+            return { bytes: bytes.length };
+          },
+          mapError(error, defaults = {}) {
+            if (error instanceof ProviderContractError) return error;
+            const aborted = error?.name === 'AbortError', timeout = error?.name === 'TimeoutError';
+            return failure('Wan transport or local delivery failed; inspect the original Core Task before taking another action.',
+              error?.stage || defaults.stage || 'submit', error?.acceptance || defaults.acceptance || 'unknown',
+              error?.category || (aborted ? 'aborted' : timeout ? 'timeout' : ['ENOSPC', 'EDQUOT', 'EACCES', 'EPERM', 'EROFS', 'EIO', 'EEXIST'].includes(error?.code) ? 'local_io' : 'network'),
+              { ...(typeof error?.code === 'string' && error.code.startsWith('IRIS_') ? { providerCode: error.code } : {}), retryable: aborted ? false : true });
+          }
+        }, unsupported: { cancel: 'Remote cancellation is outside this reference; stopping Core waiting does not cancel billing.' },
+        unsupportedPreparation: 'This text-to-image protocol does not upload source images.' });
+      }
+    } } };
+  }
+});

package/templates/provider-starter/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "iris-provider-starter-wan",
+  "version": "0.1.0",
+  "private": true,
+  "description": "An independent Wan 2.6 image Provider reference using the Iris public plugin context.",
+  "type": "module",
+  "exports": { "types": "./index.d.mts", "default": "./index.mjs" },
+  "files": ["index.mjs", "index.d.mts", "scripts", "README.md", "LICENSE"],
+  "scripts": { "setup": "node scripts/setup.mjs", "test": "node scripts/smoke.mjs" },
+  "peerDependencies": { "@mokuyoaxis/dsh-iris": ">=0.3.0-alpha.1 <0.4.0" },
+  "engines": { "node": ">=22.1.0" },
+  "license": "MIT"
+}

package/templates/provider-starter/scripts/core-cli.mjs

@@ -0,0 +1,22 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageFile = fileURLToPath(import.meta.resolve('@mokuyoaxis/dsh-iris/package.json'));
+const metadata = JSON.parse(await readFile(packageFile, 'utf8'));
+export const coreCli = path.resolve(path.dirname(packageFile), metadata.bin['dsh-iris']);
+export const cleanEnvironment = () => ({ ...process.env, IRIS_IMPORT_WORKBENCH_CONFIG: '', IRIS_CORE_CONNECTION_FILE: '', IRIS_CORE_SCOPES: '', NODE_OPTIONS: '' });
+const execute = promisify(execFile);
+export async function runCore(dataRoot, ...args) {
+  return runCli([...args, '--data-root', dataRoot]);
+}
+export async function runCli(args) {
+  const { stdout } = await execute(process.execPath, [coreCli, ...args], {
+    timeout: 30_000, maxBuffer: 2 * 1024 * 1024, env: cleanEnvironment()
+  });
+  const value = JSON.parse(stdout);
+  if (value.ok === false) throw new Error('Core command failed: ' + JSON.stringify(value));
+  return value.result ?? value;
+}

package/templates/provider-starter/scripts/environment.mjs

@@ -0,0 +1,122 @@
+// Public CLI/HTTP acceptance. No private Core imports, Task writes or alternate queues.
+import assert from 'node:assert/strict';
+import { mkdtemp, chmod, readFile, writeFile, appendFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { setup } from './setup.mjs';
+import { coreCli, cleanEnvironment, runCli } from './core-cli.mjs';
+import { createFixture } from './fixture.mjs';
+
+export const credentialEnv = 'IRIS_B4_STARTER_FIXTURE_KEY';
+export const syntheticKey = 'synthetic-b4-starter-key';
+export async function createEnvironment({ proxyUrl } = {}) {
+  const work = await mkdtemp(path.join(os.tmpdir(), 'iris-provider-starter-')); await chmod(work, 0o700);
+  // Windows kill(SIGTERM) forces termination; exercise the public CLI's normal
+  // shutdown handler through the same isolated IPC preload used by Core tests.
+  const cooperativeSignals = process.platform === 'win32' || process.env.IRIS_TEST_CLI_SIGNAL_MODE === 'ipc';
+  const signalPreload = path.join(work, 'signal-preload.mjs');
+  if (cooperativeSignals) await writeFile(signalPreload, `process.on('message', message => {
+  if (message === 'iris-test-sigterm' && !process.emit('SIGTERM')) throw new Error('CLI SIGTERM handler is not installed');
+});
+process.channel.unref();
+`, { mode: 0o600 });
+  const fixture = await createFixture();
+  const prepared = await setup({ directory: path.join(work, 'demo'), endpoint: fixture.origin, credentialEnv });
+  let networkConfigPath;
+  if (proxyUrl) {
+    const url = new URL(proxyUrl);
+    assert(url.protocol === 'http:' && url.hostname === '127.0.0.1' && url.port && !url.username && !url.password && !url.search && !url.hash && url.pathname === '/',
+      'acceptance proxy must be an explicit credential-free loopback HTTP URL');
+    networkConfigPath = path.join(work, 'network.json');
+    const command = (...args) => runCli(['network', ...args, '--network-config', networkConfigPath]);
+    let value = await command('routing', 'init');
+    value = await command('nodes', 'add', '--input', JSON.stringify({ expectedRevision: value.revision,
+      node: { id: 'fixture-net', protocol: 'http', host: '127.0.0.1', port: Number(url.port) } }));
+    value = await command('pools', 'add', '--input', JSON.stringify({ expectedRevision: value.revision,
+      pool: { id: 'fixture-pool', mode: 'fixed', candidates: [{ kind: 'node', nodeId: 'fixture-net' }] } }));
+    const routed = path.join(prepared.directory, 'providers-routed.json');
+    await command('catalog', 'create', '--provider-config', prepared.providerConfigPath, '--output', routed);
+    await command('bindings', 'set', '--provider-config', routed, '--input', JSON.stringify({ expectedRevision: value.revision, providerId: 'wan-reference', poolId: 'fixture-pool' }));
+    prepared.providerConfigPath = routed;
+  }
+  const scheduler = path.join(work, 'scheduler.json');
+  const event = (phase, detail = {}) => appendFile(path.join(work, 'events.jsonl'), JSON.stringify({ phase, at: new Date().toISOString(), ...detail }) + '\n', { mode: 0o600 });
+  await writeFile(scheduler, JSON.stringify({ schemaVersion: 1, httpConcurrency: 2, requestsPerSecond: 100, remoteLimit: 4 }), { mode: 0o600 });
+  let child, exited, exit, started, sequence = 0, serviceStderr = () => '';
+  async function start({ present = true, version, key = syntheticKey } = {}) {
+    await event('starting', { present, ...(version ? { version } : {}) });
+    let entry = prepared.entry;
+    if (version) {
+      entry = path.join(work, 'version-' + version + '.mjs');
+      // Wrap this external template, never a private Iris implementation.
+      await writeFile(entry, `import plugin from ${JSON.stringify(pathToFileURL(prepared.entry).href)};\nexport default { ...plugin, manifest: { ...plugin.manifest, version: ${JSON.stringify(version)} } };\n`, { mode: 0o600 });
+    }
+    await writeFile(prepared.configPath, JSON.stringify({ schemaVersion: 0, entries: present ? [entry] : [] }) + '\n', { mode: 0o600 });
+    const tokenFile = path.join(work, 'owner-' + (++sequence)); let stdout = '', stderr = ''; exited = false;
+    serviceStderr = () => stderr;
+    child = spawn(process.execPath, [...(cooperativeSignals ? ['--import', pathToFileURL(signalPreload).href] : []), coreCli, 'web', 'serve', '--data-root', prepared.dataRoot,
+      '--plugin-config', prepared.configPath, '--provider-config', prepared.providerConfigPath, '--allow-execution', '--allow-provider-management',
+      '--connection-store', prepared.connectionStore, '--allow-connection-management', '--allow-mcp',
+      '--scheduler-config', scheduler, '--token-file', tokenFile, ...(networkConfigPath ? ['--network-config', networkConfigPath] : [])], {
+      stdio: ['ignore', 'pipe', 'pipe', ...(cooperativeSignals ? ['ipc'] : [])], env: { ...cleanEnvironment(), [credentialEnv]: key }
+    });
+    child.stdout.on('data', bytes => { stdout += bytes; }); child.stderr.on('data', bytes => { stderr += bytes; });
+    exit = new Promise(resolve => child.once('close', (code, signal) => { exited = true; resolve({ code, signal }); }));
+    const deadline = performance.now() + 15000;
+    while (!stdout.includes('\n') && !exited && performance.now() < deadline) await delay(10);
+    assert(stdout.includes('\n'), 'Core CLI startup failed: ' + stderr);
+    started = { ...JSON.parse(stdout.split('\n')[0]), accessToken: (await readFile(tokenFile, 'utf8')).trim() };
+    await event('started', { pid: child.pid });
+    child.once('close', () => { void writeFile(path.join(work, 'service-' + sequence + '.stderr.log'), stderr, { mode: 0o600 }); });
+    return started;
+  }
+  async function stop() {
+    if (child) await event('stopping', { pid: child.pid });
+    if (child && !exited) {
+      if (cooperativeSignals) child.send('iris-test-sigterm');
+      else child.kill('SIGTERM');
+    }
+    if (child) {
+      const result = await Promise.race([exit, delay(10000, undefined, { ref: false }).then(() => { throw new Error('Core CLI did not close within 10 seconds'); })]);
+      assert.equal(result.code, 143, JSON.stringify({ ...result, stderr: serviceStderr(), work }));
+      await event('stopped', result);
+    }
+    child = undefined;
+  }
+  async function raw(route, { value, key, headers, method = value === undefined ? 'GET' : 'POST' } = {}) {
+    // Each restarted service is a distinct acceptance instance; never reuse its predecessor's idle socket.
+    return fetch(started.origin + route, { method, headers: { Connection: 'close', Authorization: 'Bearer ' + started.accessToken,
+      ...(value === undefined ? {} : { 'Content-Type': 'application/json' }), ...(key ? { 'Idempotency-Key': key } : {}), ...headers },
+      ...(value === undefined ? {} : { body: JSON.stringify(value) }), signal: AbortSignal.timeout(20000) });
+  }
+  async function http(route, options, expected = 200) {
+    const response = await raw(route, options), value = await response.json();
+    assert.equal(response.status, expected, JSON.stringify(value)); assert(!JSON.stringify(value).includes(syntheticKey)); return value;
+  }
+  async function terminal(id) {
+    for (let i = 0; i < 500; i++) {
+      const operation = (await http('/api/v0/operations/' + id)).operation;
+      if (!['queued', 'running'].includes(operation.state)) return operation;
+      await delay(10);
+    }
+    assert.fail('Operation did not finish');
+  }
+  const base = '/api/v0/connection-management/connections';
+  const listConnections = async () => (await http(base)).connections;
+  async function connection(capabilities = ['image-generate']) {
+    const value = await http(base, { value: { key: crypto.randomUUID(), label: 'Provider starter acceptance',
+      scopes: ['read', 'create', 'execute', 'stop'], capabilities } }, 201);
+    return (await listConnections()).find(record => record.connectionId === value.connectionId);
+  }
+  const exported = async record => (await http(base + '/' + record.connectionId + '/export', { value: { transport: 'http', format: 'entry' } })).configuration;
+  async function reduce(record) {
+    const current = (await listConnections()).find(item => item.connectionId === record.connectionId);
+    return http(base + '/' + record.connectionId + '/update', { value: { expectedRevision: current.revision, label: current.label,
+      scopes: ['read'], capabilities: current.capabilities, tools: current.tools, pluginOperations: current.pluginOperations } });
+  }
+  return { work, prepared, fixture, start, stop, raw, http, terminal, connection, exported, reduce,
+    get started() { return started; }, async close() { try { await stop(); } finally { await fixture.close(); } } };
+}

package/templates/provider-starter/scripts/fixture.mjs

@@ -0,0 +1,54 @@
+// Local-only acceptance service. Never a real DashScope gateway.
+import http from 'node:http';
+import { once } from 'node:events';
+import { setTimeout as delay } from 'node:timers/promises';
+
+export const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64');
+export async function createFixture() {
+  const requests = [], errors = [], tasks = new Set(); let ready = false, mode = 'normal', active = 0, peak = 0, origin, cdnOrigin, submitGate, release;
+  const sockets = new Set();
+  const track = server => server.on('connection', socket => { sockets.add(socket); socket.once('close', () => sockets.delete(socket)); });
+  const cdn = http.createServer((req, res) => {
+    requests.push({ method: req.method, path: req.url, authorization: req.headers.authorization, cdn: true });
+    if (req.url === '/redirect') { res.writeHead(302, { Location: cdnOrigin + '/image.png' }); res.end(); }
+    else { res.writeHead(200, { 'Content-Type': 'image/png' }); res.end(PNG); }
+  }); track(cdn); cdn.listen(0, '127.0.0.1'); await once(cdn, 'listening'); cdnOrigin = `http://127.0.0.1:${cdn.address().port}`;
+  async function handle(req, res) {
+    const chunks = []; for await (const chunk of req) chunks.push(chunk);
+    const row = { method: req.method, path: req.url, authorization: req.headers.authorization,
+      async: req.headers['x-dashscope-async'], body: Buffer.concat(chunks).toString('utf8'), cdn: false };
+    requests.push(row); res.setHeader('Content-Type', 'application/json');
+    if (mode === 'redirect') { res.writeHead(302, { Location: cdnOrigin + '/image.png' }); res.end(); return; }
+    if (mode === 'rate-limit') { res.writeHead(429, { 'Retry-After': '2' }); res.end('{"error":"synthetic-private-upstream-detail"}'); return; }
+    if (mode === 'html') { res.end('<html>synthetic-private-upstream-detail</html>'); return; }
+    if (mode === 'large') { res.end('x'.repeat(1024 * 1024 + 1)); return; }
+    const url = new URL(req.url, origin);
+    if (url.pathname === '/api/v1/models') {
+      const page = Number(url.searchParams.get('page_no'));
+      const models = page === 1 ? Array.from({ length: 100 }, (_, i) => ({ model: 'unsupported-fixture-' + i })) : [{ model: 'wan2.6-t2i' }];
+      res.end(JSON.stringify({ output: { total: mode === 'bad-page' && page === 2 ? 102 : 101,
+        page_no: page, page_size: 100, models } })); return;
+    }
+    if (url.pathname === '/api/v1/services/aigc/image-generation/generation' && req.method === 'POST') {
+      active++; peak = Math.max(peak, active); if (submitGate) await submitGate; else await delay(120); active--;
+      if (mode === 'reset') { req.socket.destroy(); return; }
+      if (mode === 'missing-id') { res.end('{"output":{}}'); return; }
+      const id = 'original-remote-' + (tasks.size + 1); tasks.add(id);
+      res.end(JSON.stringify({ output: { task_id: id, task_status: 'PENDING' } })); return;
+    }
+    if (url.pathname.startsWith('/api/v1/tasks/')) {
+      const id = decodeURIComponent(url.pathname.slice('/api/v1/tasks/'.length));
+      if (!tasks.has(id)) { res.writeHead(404).end('{}'); return; }
+      res.end(JSON.stringify({ output: { task_id: id, task_status: ready ? 'SUCCEEDED' : 'RUNNING',
+        ...(ready ? { choices: mode === 'bad-poll' ? {} : [{ message: { content: [{ image: cdnOrigin + '/redirect' }] } }] } : {}) } })); return;
+    }
+    res.writeHead(404).end('{}');
+  }
+  const server = http.createServer((req, res) => { void handle(req, res).catch(error => { errors.push(error.message); res.destroy(); }); });
+  track(server); server.listen(0, '127.0.0.1'); await once(server, 'listening'); origin = `http://127.0.0.1:${server.address().port}`;
+  return { origin, cdnOrigin, requests, errors, tasks, get peak() { return peak; },
+    set mode(value) { mode = value; }, set ready(value) { ready = value; },
+    holdSubmits() { submitGate = new Promise(resolve => { release = resolve; }); },
+    releaseSubmits() { release?.(); submitGate = undefined; },
+    async close() { release?.(); for (const socket of sockets) socket.destroy(); await Promise.all([server, cdn].map(item => new Promise(resolve => item.close(resolve)))); } };
+}

package/templates/provider-starter/scripts/mcp-probe.mjs

@@ -0,0 +1,21 @@
+// Acceptance client only. Harnesses import Core's exported configuration; the server uses its official MCP SDK.
+export async function mcpProbe(configuration) {
+  let sequence = 0;
+  async function request(method, params, notification = false) {
+    const id = notification ? undefined : ++sequence;
+    const response = await fetch(configuration.url, { method: 'POST', headers: {
+      ...configuration.headers, Connection: 'close', 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream',
+      'MCP-Protocol-Version': '2025-11-25'
+    }, body: JSON.stringify({ jsonrpc: '2.0', ...(notification ? {} : { id }), method, params }), signal: AbortSignal.timeout(20_000) });
+    const text = await response.text();
+    if (notification && response.status === 202) return;
+    const messages = response.headers.get('content-type')?.startsWith('text/event-stream')
+      ? text.split('\n').filter(line => line.startsWith('data:')).map(line => JSON.parse(line.slice(5))) : [JSON.parse(text)];
+    const message = messages.find(item => item.id === id) || messages.at(-1);
+    if (!response.ok || message.error) throw new Error(message.error?.message || 'MCP HTTP ' + response.status);
+    return message.result;
+  }
+  await request('initialize', { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'iris-provider-starter-test', version: '0.1.0' } });
+  await request('notifications/initialized', {}, true);
+  return { request, call: (name, args) => request('tools/call', { name, arguments: args }) };
+}

package/templates/provider-starter/scripts/protocol-smoke.mjs

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createCorePluginRegistry, ProviderContractError } from '@mokuyoaxis/dsh-iris/plugins';
+import plugin, { PROVIDER_PROTOCOL, SUPPORTED_MODEL } from '../index.mjs';
+import { createFixture, PNG } from './fixture.mjs';
+
+const fixture = await createFixture(), registry = await createCorePluginRegistry({ plugins: [plugin] });
+const work = await mkdtemp(path.join(os.tmpdir(), 'iris-wan-protocol-'));
+const adapter = registry.providers.createAdapter(PROVIDER_PROTOCOL, { id: 'p', baseUrl: fixture.origin, apiKey: 'synthetic-private-upstream-detail' });
+const methods = adapter.operations, request = { capability: 'image', model: SUPPORTED_MODEL, input: { prompt: 'local fixture', n: 1 } };
+async function rejects(action, stage, acceptance, category = 'protocol') {
+  await assert.rejects(action, error => error instanceof ProviderContractError && error.stage === stage && error.acceptance === acceptance && error.category === category
+    && !error.message.includes('synthetic-private-upstream-detail'));
+}
+try {
+  assert.deepEqual((await methods.discover({})).models, [{ id: SUPPORTED_MODEL, capabilities: ['image-gen'] }]);
+  fixture.mode = 'bad-page'; await rejects(() => methods.discover({}), 'validate', 'not_accepted');
+  fixture.mode = 'normal'; const before = fixture.requests.length;
+  await rejects(() => methods.submit({ ...request, model: 'unsupported' }), 'validate', 'not_accepted', 'invalid_request');
+  await rejects(() => methods.submit({ ...request, input: { prompt: 'x', n: 5 } }), 'validate', 'not_accepted', 'invalid_request');
+  assert.equal(fixture.requests.length, before);
+  const accepted = await methods.submit(request), remote = { capability: 'image', remoteTaskId: accepted.remoteTaskId };
+  assert.equal((await methods.poll(remote)).kind, 'pending'); fixture.ready = true;
+  fixture.mode = 'bad-poll'; await rejects(() => methods.poll(remote), 'poll', 'accepted'); fixture.mode = 'normal';
+  const result = await methods.poll(remote), targetPath = path.join(work, 'image.png');
+  assert.equal((await methods.download({ capability: 'image', artifact: result.artifacts[0], targetPath })).bytes, PNG.length);
+  assert.deepEqual(await readFile(targetPath), PNG);
+  assert(fixture.requests.filter(row => row.cdn).every(row => row.authorization === undefined));
+  await assert.rejects(methods.download({ capability: 'image', artifact: result.artifacts[0], targetPath }), { code: 'EEXIST' });
+  for (const mode of ['missing-id', 'html', 'large']) {
+    fixture.mode = mode; await rejects(() => methods.submit(request), 'response', 'unknown');
+  }
+  fixture.mode = 'rate-limit';
+  await assert.rejects(methods.submit(request), error => error.acceptance === 'not_accepted' && error.category === 'rate_limit' && error.retryAfterMs === 2000);
+  fixture.mode = 'redirect'; const cdnBefore = fixture.requests.filter(row => row.cdn).length;
+  await assert.rejects(methods.submit(request), error => {
+    const mapped = methods.mapError(error, { stage: 'submit', acceptance: 'unknown' });
+    return mapped.acceptance === 'unknown' && !mapped.message.includes('synthetic-private-upstream-detail');
+  });
+  assert.equal(fixture.requests.filter(row => row.cdn).length, cdnBefore, 'authenticated API redirects are rejected');
+  fixture.mode = 'normal'; const controller = new AbortController(); controller.abort();
+  await assert.rejects(methods.discover({ signal: controller.signal }), error => methods.mapError(error, { stage: 'validate', acceptance: 'not_accepted' }).category === 'aborted');
+  assert.deepEqual(fixture.errors, []);
+  console.log(JSON.stringify({ ok: true, work, checks: ['complete directory and invalid pagination', 'explicit model/n validation before HTTP', 'accepted original task and pending/succeeded poll',
+    'bounded Core-target delivery, no overwrite and credential-free CDN', 'unknown acceptance on malformed/oversized response', '429 cooldown hint', 'no authenticated redirect or raw error echo', 'caller cancellation'] }, null, 2));
+} finally { await registry.dispose(); await fixture.close(); }

package/templates/provider-starter/scripts/setup.mjs

@@ -0,0 +1,44 @@
+import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import plugin, { PROVIDER_PROTOCOL } from '../index.mjs';
+import { coreCli, runCore } from './core-cli.mjs';
+
+export async function setup({ directory, endpoint, credentialEnv }) {
+  if (!path.isAbsolute(directory)) throw new Error('--directory must be an absolute path to a new directory.');
+  if (typeof credentialEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(credentialEnv)) throw new Error('--credential-env must be an environment variable name, never a key value.');
+  const url = new URL(endpoint);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash
+      || /\/(?:api\/v1|compatible-mode\/v1)\/?$/.test(url.pathname)) throw new Error('--endpoint must be the explicit workspace API root, without credentials, query or /api/v1.');
+  // Resolve the existing parent so a symlink cannot put private data in the distributed project.
+  const projectRoot = await realpath(fileURLToPath(new URL('..', import.meta.url)));
+  const target = path.join(await realpath(path.dirname(directory)), path.basename(directory));
+  const relative = path.relative(projectRoot, target);
+  if (relative === '' || relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative)) throw new Error('Demo data must be outside the plugin project.');
+  // Reject all existing directories, including empty ones; leave partial output for diagnosis on failure.
+  await mkdir(target, { mode: 0o700 });
+  const dataRoot = path.join(target, 'core'), providerConfigPath = path.join(target, 'providers.json'),
+    configPath = path.join(target, 'plugins.json'), connectionStore = path.join(target, 'connections');
+  const entry = fileURLToPath(new URL('../index.mjs', import.meta.url));
+  await writeFile(configPath, JSON.stringify({ schemaVersion: 0, entries: [entry] }, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  await writeFile(providerConfigPath, JSON.stringify({ providers: [{ id: 'wan-reference', name: 'Wan reference',
+    enabled: true, baseUrl: endpoint.replace(/\/+$/, ''), apiKeyEnv: credentialEnv, mediaProtocol: PROVIDER_PROTOCOL, models: [] }],
+    assignments: { 'image-gen': { mode: 'disabled', models: [] } } }, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  await runCore(dataRoot, 'flow', 'init');
+  await runCore(dataRoot, 'execution', 'init', '--image-generation');
+  return { directory: target, dataRoot, configPath, providerConfigPath, connectionStore, entry,
+    pluginId: plugin.manifest.id,
+    startArgv: [process.execPath, coreCli, 'web', 'serve', '--data-root', dataRoot, '--plugin-config', configPath,
+      '--provider-config', providerConfigPath, '--allow-provider-management', '--allow-execution',
+      '--connection-store', connectionStore, '--allow-connection-management', '--allow-mcp', '--port', '3182'] };
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  const args = process.argv.slice(2), allowed = ['--directory', '--endpoint', '--credential-env'];
+  if (args.length !== 6 || allowed.some(name => args.filter(item => item === name).length !== 1)
+      || args.some((value, index) => index % 2 === 0 && !allowed.includes(value))) {
+    throw new Error('Usage: npm run setup -- --directory /absolute/new-private-directory --endpoint https://YOUR-WORKSPACE-API-ROOT --credential-env YOUR_KEY_VARIABLE');
+  }
+  const options = Object.fromEntries(args.reduce((pairs, value, index) => index % 2 ? [...pairs, [args[index - 1].slice(2), value]] : pairs, []));
+  console.log(JSON.stringify(await setup({ directory: options.directory, endpoint: options.endpoint, credentialEnv: options['credential-env'] }), null, 2));
+}