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

package/templates/plugin-starter/scripts/smoke.mjs

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { createEnvironment, businessId } from './environment.mjs';
+import { setup } from './setup.mjs';
+import { mcpProbe } from './mcp-probe.mjs';
+
+const env = await createEnvironment(), checks = [];
+const parsed = result => { assert(!result.isError, JSON.stringify(result)); return result.structuredContent ?? JSON.parse(result.content.find(item => item.type === 'text').text); };
+try {
+  const configBefore = await readFile(env.prepared.configPath);
+  await assert.rejects(setup(env.prepared.directory), { code: 'EEXIST' });
+  await assert.rejects(setup(env.templateRoot + '/private-demo'), /outside the plugin project/);
+  assert.deepEqual(await readFile(env.prepared.configPath), configBefore);
+  checks.push('setup rejects an existing directory without replacing its configuration');
+  await env.start({ enabled: false });
+  assert.equal((await env.http('/api/v0/connection-management/connections')).connections.length, 0);
+  const call = env.request(); await env.submit(call, 403);
+  checks.push('loading the package grants no connection access; a disabled business cannot execute');
+  await env.close(); await env.start();
+  const session = await env.http('/api/v0/session');
+  assert.equal(session.workbenchMediaReadOnly, true);
+  assert.equal(session.panelContributions.pages[0].dependency.pluginId, 'example.starter-board');
+  assert.equal(session.panelContributions.renderers[0].id, 'example.starter-board.png');
+  for (const item of [...session.panelContributions.pages, ...session.panelContributions.renderers]) {
+    for (const route of [item.entry, ...item.styles]) assert.equal((await fetch(env.started.origin + route)).status, 200);
+  }
+  checks.push('the independent page and PNG renderer are actually served from selected, pinned package assets');
+  const unselected = await env.connection([]);
+  const without = await mcpProbe((await env.exported(unselected)).configuration);
+  assert(!(await without.request('tools/list', {})).tools.some(item => item.name === 'iris_core_plugin_call'));
+  const record = await env.connection(), config = (await env.exported(record)).configuration;
+  let client = await mcpProbe(config);
+  const names = (await client.request('tools/list', {})).tools.map(item => item.name);
+  assert(names.includes('iris_core_plugin_call')); assert(!names.includes('iris_core_continue'));
+  const catalog = parsed(await client.call('iris_core_plugin_catalog', {}));
+  assert.equal(catalog.operations[0].id, businessId);
+  const accepted = parsed(await client.call('iris_core_plugin_call', call));
+  const operation = await env.terminal(accepted.operation.id); assert.equal(operation.state, 'succeeded', JSON.stringify(operation));
+  assert.deepEqual(operation.sourceArtifactIds, env.prepared.artifactIds);
+  const outputId = operation.result.artifactIds[0];
+  const bytes = Buffer.from((await client.call('iris_core_image', { artifactId: outputId })).content.find(item => item.type === 'image').data, 'base64');
+  assert.deepEqual([...bytes.subarray(0, 8)], [137, 80, 78, 71, 13, 10, 26, 10]);
+  assert.equal(bytes.readUInt32BE(16), 292); assert.equal(bytes.readUInt32BE(20), 152);
+  const digest = createHash('sha256').update(bytes).digest('hex');
+  checks.push('a user-selected, business-only connection executes the real PNG operation through formal HTTP MCP');
+  assert.equal(parsed(await client.call('iris_core_plugin_call', call)).operation.id, operation.id);
+  await env.submit({ ...call, input: { ...call.input, columns: 1 } }, 409);
+  checks.push('same UUID returns the saved Operation; changed input under that UUID is rejected');
+  await env.close(); await env.start();
+  assert.deepEqual((await env.exported(record)).configuration, config);
+  client = await mcpProbe(config);
+  assert.deepEqual(parsed(await client.call('iris_core_operation', { operationId: operation.id })).operation, operation);
+  assert.equal(parsed(await client.call('iris_core_lookup', { key: call.key })).operation.id, operation.id);
+  assert.equal((await env.http('/api/v0/plugin-operations/catalog')).artifacts.length, 3);
+  const restored = Buffer.from((await client.call('iris_core_image', { artifactId: outputId })).content.find(item => item.type === 'image').data, 'base64');
+  assert.deepEqual(restored, bytes);
+  checks.push('restart preserves the original connection, UUID, exact Operation and PNG bytes without another business execution');
+  await env.update(record, ['read']);
+  client = await mcpProbe(config);
+  assert(!(await client.request('tools/list', {})).tools.some(item => item.name === 'iris_core_plugin_call'));
+  assert.equal(parsed(await client.call('iris_core_operation', { operationId: operation.id })).operation.state, 'succeeded');
+  await assert.rejects(client.call('iris_core_plugin_call', { ...call, key: crypto.randomUUID() }), /Tool iris_core_plugin_call not found/);
+  checks.push('reduced authority removes execution tools and rejects explicit calls while retaining granted history reads');
+  await env.close(); await env.start({ version: '0.1.1' });
+  await env.submit({ ...call, key: crypto.randomUUID() }, 409);
+  assert.deepEqual((await env.http('/api/v0/operations/' + operation.id)).operation, operation);
+  checks.push('a different installed version cannot replace a saved exact plugin dependency');
+  await env.close(); await env.start({ present: false });
+  assert.deepEqual((await env.http('/api/v0/operations/' + operation.id)).operation, operation);
+  assert.deepEqual((await env.http('/api/v0/plugin-operations/catalog')).operations, []);
+  assert.deepEqual(Buffer.from(await (await env.raw('/api/v0/artifacts/' + outputId + '/content')).arrayBuffer()), bytes);
+  await env.submit({ ...call, key: crypto.randomUUID() }, 403);
+  checks.push('missing implementation blocks new execution but keeps Core history and original artifact readable');
+  console.log(JSON.stringify({ ok: true, checks, work: env.work, operationId: operation.id, artifactId: outputId, sha256: digest }, null, 2));
+} finally { await env.close(); }

package/templates/plugin-starter/web/board.css

@@ -0,0 +1,27 @@
+.starter-intro { margin-bottom:24px; }
+.starter-eyebrow { color:var(--accent); font-size:11px; letter-spacing:1.5px; }
+.starter-intro h2 { font-size:clamp(21px,3vw,28px); letter-spacing:-.6px; margin:8px 0; }
+.starter-intro::after { content:""; display:block; height:3px; width:80px; border-radius:9px; margin-top:20px; background:linear-gradient(105deg,#45317D,#6F69B8,#BB78AD,#E59B76,#ED9C91,#F0D09C); }
+.muted { color:var(--muted); font-size:13px; line-height:1.6; }
+.starter-layout { display:grid; grid-template-columns:minmax(0,1fr) 220px; gap:20px; align-items:start; }
+.starter-choices { display:grid; grid-template-columns:repeat(auto-fill,minmax(110px,1fr)); gap:12px; min-width:0; }
+.starter-choice { position:relative; padding:10px; border:1px solid var(--line); border-radius:12px; background:var(--soft); cursor:pointer; }
+.starter-choice:has(input:checked) { border-color:var(--accent); background:var(--tint); }
+.starter-choice input { position:absolute; top:10px; left:10px; }
+.starter-choice img { display:block; width:100%; height:120px; object-fit:contain; border-radius:6px; }
+.starter-choice span { display:block; text-align:center; margin-top:8px; overflow-wrap:anywhere; }
+.starter-editor { padding:18px; border:1px solid var(--line); border-radius:14px; background:var(--soft); }
+.starter-editor label { display:block; font-size:13px; margin-bottom:14px; }
+.starter-editor select { display:block; width:100%; margin-top:6px; min-height:40px; padding:6px; border:1px solid var(--line); border-radius:8px; color:var(--ink); background:var(--panel); }
+.starter-editor button { display:block; width:100%; min-height:42px; margin:10px 0; border:0; border-radius:8px; padding:9px; background:var(--accent); color:var(--on-accent); cursor:pointer; }
+.starter-editor button:disabled { opacity:.5; cursor:default; }
+.starter-editor .secondary { border:1px solid var(--line); background:transparent; color:var(--ink); }
+.starter-editor details { margin-top:18px; font-size:13px; }
+.starter-editor summary { cursor:pointer; }
+.starter-status { font-size:13px; line-height:1.8; overflow-wrap:anywhere; margin:20px 0; }
+.starter-result { border-top:1px solid var(--line); padding-top:20px; }
+.starter-result img, .starter-preview img { display:block; max-width:100%; max-height:600px; object-fit:contain; margin:0 auto 16px; }
+.starter-result a { display:inline-block; padding:10px 14px; border:1px solid var(--line); border-radius:8px; color:var(--accent); }
+:focus-visible { outline:2px solid var(--accent); outline-offset:3px; }
+[hidden] { display:none !important; }
+@media(max-width:680px) { .starter-layout { grid-template-columns:1fr; } .starter-editor { order:-1; } }

package/templates/plugin-starter/web/board.mjs

@@ -0,0 +1,160 @@
+const element = (tag, text, className) => {
+  const node = document.createElement(tag);
+  if (text) node.textContent = text;
+  if (className) node.className = className;
+  return node;
+};
+
+export async function mount({ container, api, session, dependency, signal: parentSignal, theme }) {
+  const lifetime = new AbortController(), signal = AbortSignal.any([parentSignal, lifetime.signal]);
+  const service = api.pluginOperations, urls = new Set();
+  const operationId = dependency.pluginId + '.create';
+  const storageKey = operationId + ':' + session.rootId;
+  let receipt, selected = [], catalog, busy = false, timer, renderedId, unsubscribe, closed = false;
+  function cleanup() {
+    if (closed) return;
+    closed = true; lifetime.abort(); clearTimeout(timer); unsubscribe?.();
+    for (const url of urls) URL.revokeObjectURL(url);
+    urls.clear(); container.replaceChildren();
+  }
+  signal.addEventListener('abort', cleanup, { once: true });
+  const intro = element('header', '', 'starter-intro');
+  intro.append(element('span', 'LOCAL · NO MODEL CALLS', 'starter-eyebrow'), element('h2', '让灵感，并排相遇。'),
+    element('p', '选择图片，制作一张属于你的灵感对照板。', 'muted'));
+  const layout = element('div', '', 'starter-layout'), choices = element('div', '', 'starter-choices');
+  choices.setAttribute('aria-label', '选择来源图片');
+  const editor = element('form', '', 'starter-editor');
+  const columnsLabel = element('label', '每行图片数'), columns = document.createElement('select'); columns.name = 'columns';
+  for (let i = 1; i <= 4; i++) columns.add(new Option(String(i), String(i)));
+  columns.value = '2'; columnsLabel.append(columns);
+  const sizeLabel = element('label', '单张边长'), size = document.createElement('select'); size.name = 'size';
+  for (const n of [128, 256, 512]) size.add(new Option(n + ' px', String(n)));
+  size.value = '256'; sizeLabel.append(size);
+  const count = element('p', '尚未选择图片', 'muted'), submit = element('button', '制作对照板');
+  submit.type = 'submit'; submit.disabled = true;
+  const recover = element('button', '查询原操作', 'secondary'); recover.type = 'button'; recover.hidden = true;
+  const fresh = element('button', '新建一张', 'secondary'); fresh.type = 'button'; fresh.hidden = true;
+  const more = element('button', '加载更多图片', 'secondary'); more.type = 'button'; more.hidden = true;
+  const details = element('details'), summary = element('summary', '使用说明');
+  details.append(summary, element('p', '按选择顺序排版，最多 16 张。作品保存在 Core；刷新只查询原操作，不会自动重新制作。', 'muted'));
+  editor.append(columnsLabel, sizeLabel, count, submit, recover, fresh, more, details);
+  const status = element('p', '正在读取现有图片…', 'starter-status');
+  status.setAttribute('role', 'status');
+  const output = element('section', '', 'starter-result'); output.hidden = true;
+  layout.append(choices, editor); container.append(intro, layout, status, output);
+  function remember(value) {
+    value ? sessionStorage.setItem(storageKey, JSON.stringify(value)) : sessionStorage.removeItem(storageKey);
+    receipt = value;
+  }
+  function controls() {
+    const locked = busy || Boolean(receipt);
+    submit.disabled = locked || !selected.length || !catalog?.operations.some(item => item.id === operationId && item.available);
+    columns.disabled = size.disabled = locked; more.disabled = busy;
+    for (const checkbox of choices.querySelectorAll('input')) checkbox.disabled = locked || !checkbox.checked && selected.length >= 16;
+  }
+  function note(error) { status.textContent = [error.message, error.code, error.requestId].filter(Boolean).join(' · '); }
+  async function present(operation) {
+    signal.throwIfAborted();
+    if (operation.action !== 'plugin.execute' || operation.operationId !== operationId) throw new Error('此恢复标识属于另一项业务，请到业务记录核对。');
+    status.textContent = ({ queued: '已接收，等待处理', running: '正在排版', succeeded: '对照板已保存',
+      interrupted: '操作已中断，不会自动重做', canceled: '已停止，记录保留', failed: '操作未完成，请查看业务记录' })[operation.state] + ' · ' + operation.id;
+    fresh.hidden = ['queued', 'running'].includes(operation.state); recover.hidden = true;
+    if (operation.state === 'succeeded' && renderedId !== operation.id) {
+      const id = operation.result.artifactIds[0];
+      const blob = await api.artifact({ id, mediaType: 'image/png' }, { signal }); signal.throwIfAborted();
+      const url = URL.createObjectURL(blob); urls.add(url);
+      const image = element('img'); image.src = url; image.alt = '已保存的灵感对照板';
+      const link = element('a', '下载原始 PNG'); link.href = url; link.download = 'iris-board-' + id + '.png';
+      output.replaceChildren(image, link); output.hidden = false; renderedId = operation.id;
+    } else if (['queued', 'running'].includes(operation.state)) {
+      clearTimeout(timer); timer = setTimeout(() => { void poll(operation.id); }, 450);
+    }
+  }
+  async function poll(id) {
+    try { await present((await service.inspect(id, { signal })).operation); }
+    catch (error) { if (!signal.aborted) { note(error); recover.hidden = false; } }
+  }
+  async function lookup() {
+    if (busy || !receipt) return;
+    busy = true; controls();
+    try { await present((await service.lookup(receipt.key, { signal })).operation); }
+    catch (error) { if (!signal.aborted) { note(error); recover.hidden = false; if (error.status === 404) fresh.hidden = false; } }
+    finally { busy = false; if (!signal.aborted) controls(); }
+  }
+  editor.addEventListener('submit', async event => {
+    event.preventDefault();
+    if (busy || receipt || !selected.length) return;
+    const contribution = catalog.operations.find(item => item.id === operationId && item.available);
+    if (!contribution) return;
+    busy = true;
+    // Save the UUID before submitting. Recovery only looks up this UUID.
+    try { remember({ key: crypto.randomUUID() }); }
+    catch { busy = false; status.textContent = '浏览器无法保存恢复标识，本次未提交。请允许会话存储后再试。'; controls(); return; }
+    controls();
+    status.textContent = '正在保存本次操作 · ' + receipt.key;
+    try {
+      const accepted = await service.execute({ key: receipt.key, operationId, dependency: contribution.dependency,
+        input: { artifactIds: [...selected], columns: Number(columns.value), cellSize: Number(size.value) } }, { signal });
+      await present(accepted.operation);
+    } catch (error) {
+      if (!signal.aborted) { note(error); status.textContent += '。请查询原操作；未自动重做。'; recover.hidden = false; }
+    } finally { busy = false; if (!signal.aborted) controls(); }
+  }, { signal });
+  recover.addEventListener('click', () => { void lookup(); }, { signal });
+  fresh.addEventListener('click', () => {
+    if (busy) return;
+    try { remember(null); }
+    catch { status.textContent = '无法清除恢复标识，原操作保留；请先检查浏览器存储。'; return; }
+    renderedId = undefined; output.hidden = true; output.replaceChildren();
+    // Only keep URLs that still back source thumbnails.
+    const thumbnails = new Set([...choices.querySelectorAll('img')].map(image => image.src));
+    for (const url of urls) if (!thumbnails.has(url)) { URL.revokeObjectURL(url); urls.delete(url); }
+    fresh.hidden = recover.hidden = true; status.textContent = '选择图片后，可以新建一次操作。'; controls();
+  }, { signal });
+  async function appendImages(page) {
+    for (const artifact of page.artifacts) {
+      const label = element('label', '', 'starter-choice'), checkbox = document.createElement('input');
+      checkbox.type = 'checkbox'; checkbox.value = artifact.id;
+      const image = element('img'); image.alt = '来源图片 ' + artifact.id;
+      label.append(checkbox, image, element('span', artifact.id.slice(-8), 'muted')); choices.append(label);
+      const blob = await api.artifact({ id: artifact.id, mediaType: artifact.mediaType }, { signal }); signal.throwIfAborted();
+      const url = URL.createObjectURL(blob); urls.add(url); image.src = url;
+      checkbox.addEventListener('change', () => {
+        selected = checkbox.checked ? [...selected, artifact.id] : selected.filter(id => id !== artifact.id);
+        count.textContent = '已选择 ' + selected.length + ' 张 · 按选择顺序排版'; controls();
+      }, { signal });
+    }
+    more.hidden = page.nextOffset === null || page.nextOffset === undefined; controls();
+  }
+  more.addEventListener('click', async () => {
+    if (busy || catalog.nextOffset === null) return;
+    busy = true; controls();
+    try {
+      catalog = await service.catalog({ limit: '30', offset: String(catalog.nextOffset) }, { signal });
+      signal.throwIfAborted(); await appendImages(catalog);
+    } catch (error) { if (!signal.aborted) note(error); }
+    finally { busy = false; if (!signal.aborted) controls(); }
+  }, { signal });
+  try {
+    signal.throwIfAborted();
+    const updateTheme = value => { container.dataset.theme = value.mode; };
+    updateTheme(theme.current()); unsubscribe = theme.subscribe(updateTheme);
+    if (!service) { status.textContent = '此服务尚未启用插件业务执行，请核对启动配置。'; return cleanup; }
+    catalog = await service.catalog({ limit: '30' }, { signal }); signal.throwIfAborted();
+    await appendImages(catalog);
+    status.textContent = catalog.artifacts.length ? '选择图片即可开始，不调用模型。' : '还没有图片。请先通过创作页或 CLI 导入。';
+    let saved;
+    try { saved = sessionStorage.getItem(storageKey); }
+    catch { status.textContent = '无法读取浏览器恢复标识，请到业务记录查看已有操作。'; }
+    if (saved) {
+      try {
+        receipt = JSON.parse(saved);
+        if (!receipt || !/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(receipt.key)) throw new Error('invalid receipt');
+      } catch {
+        receipt = { invalid: true }; status.textContent = '浏览器恢复标识损坏，请核对业务记录后点击新建。'; fresh.hidden = false;
+      }
+      if (!receipt.invalid) await lookup();
+    }
+    controls(); return cleanup;
+  } catch (error) { cleanup(); throw error; }
+}

package/templates/plugin-starter/web/png.mjs

@@ -0,0 +1,23 @@
+export async function mount({ container, artifact, api, signal: parentSignal, theme }) {
+  const lifetime = new AbortController(), signal = AbortSignal.any([parentSignal, lifetime.signal]);
+  let url, unsubscribe, closed = false;
+  const image = new Image(); image.alt = 'Core 中保存的原始 PNG';
+  function cleanup() {
+    if (closed) return;
+    closed = true; lifetime.abort(); unsubscribe?.();
+    if (url) URL.revokeObjectURL(url);
+    image.removeAttribute('src'); container.replaceChildren();
+  }
+  signal.addEventListener('abort', cleanup, { once: true });
+  try {
+    const bytes = await api.artifact(artifact, { signal }); signal.throwIfAborted();
+    url = URL.createObjectURL(bytes); image.src = url;
+    await image.decode(); signal.throwIfAborted();
+    const caption = document.createElement('p'); caption.className = 'muted';
+    caption.textContent = image.naturalWidth + ' × ' + image.naturalHeight + ' · ' + bytes.size.toLocaleString() + ' bytes';
+    const update = value => { container.dataset.theme = value.mode; };
+    update(theme.current()); unsubscribe = theme.subscribe(update);
+    container.classList.add('starter-preview'); container.append(image, caption);
+    return cleanup;
+  } catch (error) { cleanup(); throw error; }
+}

package/templates/provider-starter/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Messia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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;
+}