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

package/lib/provider-network.js

@@ -0,0 +1,52 @@
+// Internal composition port. No proxy configuration, global mutation or automatic retry.
+export function inheritedProviderFetch(...args) { return globalThis.fetch(...args); }
+
+function closed() {
+  return Object.assign(new Error('Provider 网络客户端正在关闭或已关闭'), {
+    code: 'IRIS_PROVIDER_NETWORK_CLOSED', stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted'
+  });
+}
+
+export function assertProviderNetwork(network) {
+  if (!network || typeof network.fetch !== 'function' || typeof network.run !== 'function') {
+    throw new TypeError('network 需要实例级 fetch 和完整操作 run');
+  }
+  return network;
+}
+
+/** The owner drains Core/registry operations before disposing this client. */
+export function createProviderNetworkClient({ fetchPort, close } = {}) {
+  if (fetchPort !== undefined && typeof fetchPort !== 'function') throw new TypeError('fetchPort 必须是函数');
+  if (close !== undefined && typeof close !== 'function') throw new TypeError('close 必须是函数');
+  const active = new Set();
+  let state = 'open', disposal, cleanupFailed = false;
+  const snapshot = () => Object.freeze({ state, activeOperations: active.size, cleanupFailed });
+
+  // Used inside run: closing must still permit later pages, uploads and body reads.
+  const fetch = (...args) => {
+    if (state === 'closed') return Promise.reject(closed());
+    return (fetchPort || inheritedProviderFetch)(...args);
+  };
+  function run(action) {
+    if (typeof action !== 'function') throw new TypeError('网络操作必须是函数');
+    if (state !== 'open') return Promise.reject(closed());
+    const operation = Promise.resolve().then(() => action(fetch));
+    active.add(operation);
+    void operation.then(() => active.delete(operation), () => active.delete(operation));
+    return operation;
+  }
+  function dispose() {
+    if (!disposal) {
+      state = 'closing';
+      disposal = (async () => {
+        await Promise.allSettled([...active]);
+        try { await close?.(); }
+        catch (error) { cleanupFailed = true; throw error; }
+        finally { state = 'closed'; }
+        return snapshot();
+      })();
+    }
+    return disposal;
+  }
+  return Object.freeze({ fetch, run, dispose, snapshot });
+}

package/lib/provider-protocol.js

@@ -1,6 +1,7 @@
 'use strict';
 /** 供应商媒体协议判断与 DashScope 凭据边界。 */
 import { comfyWorkflowDigest } from './comfyui-workflow.js';
+import { providerCredentialValue, providerCredentialStatus } from './provider-credentials.js';
 
 const DASH_SCOPE_HOST = /^dashscope(?:-[a-z0-9-]+)?\.aliyuncs\.com$/i;
 const REGIONAL_HOST = /^cn-hongkong\.dashscope\.aliyuncs\.com$/i;
@@ -114,7 +115,7 @@ export function dashscopeApiBase(baseUrl) {
 
 /** 无认证模式不发送保留的旧凭据；未声明模式保持 bearer 兼容。 */
 export function providerApiKey(provider) {
-  return provider?.auth === 'none' ? '' : String(provider?.apiKey || '');
+  return provider?.auth === 'none' ? '' : providerCredentialValue(provider);
 }
 
 /** 配置管理与 headless 候选链共用可用性门，未声明 enabled 时默认启用。 */
@@ -122,7 +123,7 @@ export function isConfiguredProvider(provider) {
   return Boolean(provider && provider.enabled !== false
     && typeof provider.id === 'string' && provider.id.trim()
     && providerMediaBaseUrl(provider)
-    && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
+    && (provider.auth === 'none' || providerCredentialStatus(provider) === 'ready'));
 }
 
 /** 已知需要其他接口的语音系列；自定义模型仍以明确配置和实测为准。 */

package/lib/provider-registry.js

@@ -1,6 +1,9 @@
 import { defineProviderAdapter } from './provider-adapter.js';
 import { unsupportedProtocolError, providerApiKey } from './provider-protocol.js';
 import { checkedPluginDependency, assertPluginDependencyMatches } from './plugin-contract.js';
+import { createProviderNetworkClient } from './provider-network.js';
+import { createProviderContext, markProviderContextAdapter } from './provider-context.js';
+import { resolveProviderCredential } from './provider-credentials.js';
 
 export const PROVIDER_EXTENSION_CONTRACT_VERSION = 0;
 const ID = /^[a-z][a-z0-9._-]{0,79}$/;
@@ -40,7 +43,8 @@ function checkedProtocol(value) {
 /** One registry owns its factory instances, active calls and serial asynchronous cleanup. */
 export async function createExtensionRegistry(factories) {
   const protocols = new Map(), extensions = [], active = new Set();
-  let state = 'loading', disposal, cleanupFailed = false;
+  let state = 'loading', disposal, cleanupFailed = false, inherited;
+  const inheritedNetwork = () => inherited ||= createProviderNetworkClient();
 
   function dispose() {
     if (!disposal) {
@@ -48,6 +52,7 @@ export async function createExtensionRegistry(factories) {
       disposal = (async () => {
         await Promise.allSettled([...active]);
         const errors = [];
+        try { await inherited?.dispose(); } catch (error) { errors.push(error); }
         for (const extension of [...extensions].reverse()) {
           try { await extension.dispose?.(); } catch (error) { errors.push(error); }
         }
@@ -101,7 +106,10 @@ export async function createExtensionRegistry(factories) {
       if (state !== 'active') throw closed();
       const descriptor = protocols.get(id);
       if (!descriptor) throw unsupportedProtocolError(id);
-      const value = descriptor.createAdapter({ ...provider, apiKey: providerApiKey(provider) }, options);
+      const author = descriptor.dependency ? createProviderContext(provider, options, inheritedNetwork) : undefined;
+      const resolved = author ? resolveProviderCredential(provider) : provider;
+      const connection = { ...resolved, apiKey: providerApiKey(resolved) };
+      const value = descriptor.createAdapter(author ? Object.freeze(connection) : connection, author?.context || options);
       if (!value || typeof value.then === 'function') throw invalid('createAdapter 必须同步返回 Adapter');
       if (value.pluginDependency !== undefined) assertPluginDependencyMatches(descriptor.dependency, value.pluginDependency);
       const adapter = defineProviderAdapter({ ...value,
@@ -109,9 +117,11 @@ export async function createExtensionRegistry(factories) {
         unsupported: Object.fromEntries(Object.entries(value.unsupported || {}).map(([name, reason]) => [name, reason?.reason ?? reason])) });
       if (adapter.id !== provider.id || adapter.protocol !== id || adapter.capabilities.some(cap =>
         !descriptor.capabilities.some(known => CAPS[known] === cap))) throw invalid('Adapter 身份或能力与注册协议不一致');
-      return Object.freeze({ ...adapter, operations: Object.freeze(Object.fromEntries(Object.entries(adapter.operations)
-        .map(([name, action]) => [name, name === 'mapError' ? action : wrap(action)]))),
-      ...(adapter.prepareInput ? { prepareInput: wrap(adapter.prepareInput) } : {}) });
+      const operation = (name, action) => wrap(author ? (...args) => author.invoke(name, action, args) : action);
+      const result = Object.freeze({ ...adapter, operations: Object.freeze(Object.fromEntries(Object.entries(adapter.operations)
+        .map(([name, action]) => [name, name === 'mapError' ? action : operation(name, action)]))),
+      ...(adapter.prepareInput ? { prepareInput: operation('prepareInput', adapter.prepareInput) } : {}) });
+      return author ? markProviderContextAdapter(result) : result;
     },
     dispose
   });

package/lib/provider-response.js

@@ -3,6 +3,16 @@ import { ProviderContractError } from './provider-contract.js';
 export const PROVIDER_RESPONSE_LIMITS = Object.freeze({ json: 2 * 1024 * 1024, mediaJson: 128 * 1024 * 1024,
   image: 64 * 1024 * 1024, audio: 128 * 1024 * 1024, transcript: 8 * 1024 * 1024, video: 1024 * 1024 * 1024 });
 
+/** Core materialization uses the same limits as provider downloads, including cached bytes. */
+export function assertProviderMediaSize(size, capability) {
+  const maxBytes = { image: PROVIDER_RESPONSE_LIMITS.image, video: PROVIDER_RESPONSE_LIMITS.video,
+    tts: PROVIDER_RESPONSE_LIMITS.audio, music: PROVIDER_RESPONSE_LIMITS.audio, transcribe: PROVIDER_RESPONSE_LIMITS.transcript }[capability];
+  if (maxBytes === undefined) throw new TypeError('未知的媒体交付能力：' + capability);
+  if (size > maxBytes) throw Object.assign(new ProviderContractError('供应商媒体超过允许的大小（' + maxBytes + ' 字节）', {
+    stage: 'download', category: 'protocol', acceptance: 'accepted', retryable: false
+  }), { code: 'IRIS_PROVIDER_RESPONSE_TOO_LARGE' });
+}
+
 /** Count decoded response bytes as well as Content-Length: chunked and compressed
  * responses cannot bypass the limit. Iterator cancellation closes the body. */
 export async function* boundedProviderBody(response, { maxBytes, stage = 'response', acceptance = 'unknown' }) {

package/lib/provider-settings.js

@@ -1,9 +1,10 @@
-// Owner-only editing boundary. No I/O, secrets in projections, or implicit model authorization.
+// Owner-only editing boundary. No file I/O, secrets in projections, or implicit model authorization.
 import { CAPABILITIES } from './capability.js';
 import { providerModels, modelPool, functionPolicy, savedAssignmentRefs, resolvePoolModel } from './models.js';
 import { BUILTIN_PROVIDER_PROTOCOLS, normalizeMediaEndpoint, normalizeImageProtocol, normalizeMusicProtocol, selectMediaProtocol, providerForModelBinding, isConfiguredProvider } from './provider-protocol.js';
 import { clearModelCapabilityHealth, resetHealthOnCriticalChange } from './provider-health.js';
 import { checkedComfyWorkflow, projectComfyWorkflow } from './comfyui-workflow.js';
+import { validateProviderCredential, providerCredentialStatus, scrubProviderSecrets } from './provider-credentials.js';
 
 const CAPS = Object.values(CAPABILITIES);
 const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_CONFIG_INPUT_INVALID' }); };
@@ -28,7 +29,8 @@ export function projectProviderSettings(catalog, revision, registry) {
     providers: catalog.providers.map(provider => ({ id: provider.id, name: provider.name || provider.id,
       baseUrl: provider.baseUrl || '', mediaBaseUrl: provider.mediaBaseUrl || '',
       enabled: provider.enabled !== false, auth: provider.auth === 'none' ? 'none' : 'bearer',
-      hasCredential: Boolean(provider.apiKey), configured: isConfiguredProvider(provider),
+      hasCredential: providerCredentialStatus(provider) === 'ready', configured: isConfiguredProvider(provider),
+      ...(provider.apiKeyEnv !== undefined ? { apiKeyEnv: provider.apiKeyEnv, credentialStatus: providerCredentialStatus(provider) } : {}),
       mediaProtocol: selectMediaProtocol(provider).mediaProtocol,
       models: providerModels(provider).map(model => ({ id: model.id, ref: model.ref, capabilities: model.capabilities,
         imageProtocol: model.imageProtocol || 'auto', musicProtocol: model.musicProtocol || '',
@@ -44,17 +46,13 @@ export function projectProviderSettings(catalog, revision, registry) {
       return [cap, { ...policy, models: savedAssignmentRefs(pool, cap, policy.models) }];
     })) };
   // A mistakenly pasted key in a display field must not become a key read-back route.
-  const keys = catalog.providers.map(provider => provider.apiKey).filter(key => typeof key === 'string' && key);
-  const scrub = value => typeof value === 'string' ? keys.reduce((s, key) => s.split(key).join('[redacted]'), value)
-    : Array.isArray(value) ? value.map(scrub) : value && typeof value === 'object'
-      ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scrub(item)])) : value;
-  return scrub(result);
+  return scrubProviderSecrets(result, catalog.providers);
 }
 
 export function applyProviderSettings(catalog, input, registry) {
   object(input, ['expectedRevision', 'provider', 'credential', 'assignments']);
   object(input.provider, ['id', 'name', 'baseUrl', 'mediaBaseUrl', 'mediaProtocol', 'enabled', 'auth', 'models']);
-  object(input.credential, ['action', 'value']);
+  object(input.credential, ['action', 'value', 'name']);
   const value = input.provider, id = string(value.id, 160);
   const matches = catalog.providers.filter(item => item.id === id);
   if (matches.length > 1) fail('供应商 ID 重复，请在本机核对');
@@ -68,9 +66,13 @@ export function applyProviderSettings(catalog, input, registry) {
   catch (_) { fail('地址必须是无凭据、查询或片段的 HTTP(S) URL'); }
   if (!protocols(registry).some(item => item.id === next.mediaProtocol) && previous?.mediaProtocol !== next.mediaProtocol) fail('协议未注册，请先显式加载对应扩展');
   const credential = input.credential;
-  if (!['keep', 'replace', 'clear'].includes(credential.action) || credential.action !== 'replace' && Object.hasOwn(credential, 'value')) fail('密钥操作必须是 keep、replace 或 clear');
-  if (credential.action === 'replace') next.apiKey = string(credential.value, 8192);
-  if (credential.action === 'clear') delete next.apiKey;
+  if (!['keep', 'replace', 'clear', 'env'].includes(credential.action)
+      || credential.action !== 'replace' && Object.hasOwn(credential, 'value')
+      || credential.action !== 'env' && Object.hasOwn(credential, 'name')) fail('密钥操作必须是 keep、replace、clear 或 env，并只提供对应字段');
+  if (credential.action === 'replace') { next.apiKey = string(credential.value, 8192); delete next.apiKeyEnv; }
+  if (credential.action === 'env') { next.apiKeyEnv = string(credential.name, 128); delete next.apiKey; }
+  if (credential.action === 'clear') { delete next.apiKey; delete next.apiKeyEnv; }
+  validateProviderCredential(next);
   if (!Array.isArray(value.models) || value.models.length > 256) fail('单次最多保存 256 个模型');
   const existing = providerModels(previous || {});
   const entries = Array.isArray(previous?.models) ? previous.models.map(model => typeof model === 'string' ? { id: model } : { ...model })
@@ -102,7 +104,7 @@ export function applyProviderSettings(catalog, input, registry) {
     resetHealthOnCriticalChange(previousConnection, next, next);
     for (const model of existing) {
       const updated = next.models.find(entry => entry.id === model.id);
-      const connectionChanged = ['apiKey', 'baseUrl', 'mediaBaseUrl', 'auth', 'mediaProtocol'].some(key => previousConnection[key] !== next[key]);
+      const connectionChanged = ['apiKey', 'apiKeyEnv', 'baseUrl', 'mediaBaseUrl', 'auth', 'mediaProtocol'].some(key => previousConnection[key] !== next[key]);
       for (const cap of model.capabilities) if (connectionChanged || !updated.capabilities?.includes(cap)
         || cap === 'image-gen' && JSON.stringify(previous.models?.find(entry => entry?.id === model.id)?.comfyWorkflow) !== JSON.stringify(updated.comfyWorkflow)
         || cap === 'image-gen' && providerForModelBinding(previous, model.id, cap).mediaProtocol !== providerForModelBinding(next, model.id, cap).mediaProtocol

package/lib/provider-task-runner.js

@@ -20,6 +20,7 @@ import {
   recordCoreAttemptResult,
   recordCoreCancelResult,
   recordCoreDownloadCompleted,
+  recordCoreNetworkRoute,
   recordCorePollResult,
   recordCoreWatchError,
   recoverCoreTask,
@@ -38,6 +39,8 @@ import { createDeliveryCache, newDeliveryPayloadPath, readDeliveryCache,
 import { readFlowRun, flowFail, flowStep } from './flow-store.js';
 import { normalizeGenerationInput } from './generation-input.js';
 import { assertPluginDependencyMatches } from './plugin-contract.js';
+import { checkedNetworkRequirement, sameNetworkRequirement, createNetworkAttemptBudget } from './network-policy.js';
+import { assertProviderMediaSize } from './provider-response.js';
 
 export const PROVIDER_TASK_RUNNER_VERSION = 0;
 
@@ -48,7 +51,7 @@ export const PROVIDER_TASK_RUNNER_VERSION = 0;
  */
 export const DELIVERY_PROFILES = Object.freeze({
   image: Object.freeze({ kind: 'generated-image', mediaTypes: Object.freeze(['image/png', 'image/jpeg', 'image/webp']), defaultMediaType: 'image/png' }),
-  video: Object.freeze({ kind: 'generated-video', mediaTypes: Object.freeze(['video/mp4']), defaultMediaType: 'video/mp4' }),
+  video: Object.freeze({ kind: 'generated-video', mediaTypes: Object.freeze(['video/mp4', 'video/webm']), defaultMediaType: 'video/mp4' }),
   // TTS 同步完成型：submit 内 completed → 同一次调用直接交付（无 remote 长轮询）。
   tts: Object.freeze({ kind: 'generated-audio', mediaTypes: Object.freeze(['audio/mpeg', 'audio/wav']), defaultMediaType: 'audio/mpeg' }),
   music: Object.freeze({ kind: 'generated-audio', mediaTypes: Object.freeze(['audio/mpeg', 'audio/wav']), defaultMediaType: 'audio/mpeg' }),
@@ -57,6 +60,20 @@ export const DELIVERY_PROFILES = Object.freeze({
 });
 const runtimeTaskGates = new WeakMap();
 
+// The Core operation owns the root and route persistence, including when the
+// network manager is supplied by a caller rather than created by CLI/Web.
+function networkOperationContext(runtime, dataRoot, taskId, context) {
+  const task = inspectCoreTask(dataRoot, taskId);
+  return { ...context, taskId, modelRef: task.modelRef, providerId: task.providerId,
+    ...(runtime.reportScheduling ? { onSchedulingState: runtime.reportScheduling } : {}),
+    recordNetworkRoute: fact => runtime.checkpoint ? runtime.checkpoint(() => recordCoreNetworkRoute(dataRoot, taskId, fact)) : recordCoreNetworkRoute(dataRoot, taskId, fact) };
+}
+
+function invokeNetwork(runtime, adapter, name, request, context) {
+  const invoke = () => invokeProviderOperation(adapter, name, request, context);
+  return runtime.networkWait ? runtime.networkWait(invoke, name) : invoke();
+}
+
 export class ProviderTaskRunnerError extends Error {
   constructor(code, message) {
     super(message);
@@ -76,12 +93,16 @@ function checkAdapterForTask(task, adapter) {
     throw new ProviderTaskRunnerError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Provider Adapter 与 Task 已持久化身份不一致');
   }
   assertPluginDependencyMatches(task.pluginDependency, adapter.pluginDependency);
+  const requirement = adapter.networkRequirement === undefined ? undefined : checkedNetworkRequirement(adapter.networkRequirement);
+  if (!sameNetworkRequirement(task.networkRequirement, requirement)) {
+    throw new ProviderTaskRunnerError('IRIS_NETWORK_REQUIREMENT_MISMATCH', 'Provider 网络要求与原 Task 不一致；不会隐式升级、解除或借用其他网络配置');
+  }
   return adapter;
 }
 
 function normalizedCandidates(capability, candidates) {
   if (!Array.isArray(candidates) || !candidates.length) throw new TypeError('至少需要一个 Provider 候选');
-  return candidates.map((candidate, index) => {
+  const normalized = candidates.map((candidate, index) => {
     const adapter = candidate?.adapter;
     const model = String(candidate?.model || '').trim();
     const parsed = parseModelRef(model);
@@ -95,9 +116,18 @@ function normalizedCandidates(capability, candidates) {
     }
     if (candidate.prepareInput !== undefined && typeof candidate.prepareInput !== 'function') throw new TypeError('候选 prepareInput 必须是函数');
     if (candidate.supportsImageEdit !== undefined && typeof candidate.supportsImageEdit !== 'boolean') throw new TypeError('候选 supportsImageEdit 必须是布尔值');
+    const networkRequirement = adapter.networkRequirement === undefined ? undefined : checkedNetworkRequirement(adapter.networkRequirement);
+    if (candidate.networkRequirement !== undefined && !sameNetworkRequirement(checkedNetworkRequirement(candidate.networkRequirement), networkRequirement)) {
+      throw new ProviderTaskRunnerError('IRIS_NETWORK_REQUIREMENT_MISMATCH', '候选与 Adapter 的网络要求不一致');
+    }
     return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, pluginDependency: adapter.pluginDependency, selectionReason, prepareInput: candidate.prepareInput,
+      ...(networkRequirement ? { networkRequirement } : {}),
       ...(candidate.supportsImageEdit !== undefined ? { supportsImageEdit: candidate.supportsImageEdit } : {}) };
   });
+  if (normalized.some(candidate => !sameNetworkRequirement(candidate.networkRequirement, normalized[0].networkRequirement))) {
+    throw new ProviderTaskRunnerError('IRIS_NETWORK_REQUIREMENT_MISMATCH', '同一 Task 的所有模型候选必须属于同一网络要求');
+  }
+  return normalized;
 }
 
 function stagingFile(dataRoot) {
@@ -121,7 +151,20 @@ async function generatedImageMediaType(bytes) {
   return mediaType;
 }
 
-async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, signal) {
+/** Confirm the saved container, independently of an adapter's declared MIME; never buffer long audio. */
+function generatedAudioMediaType(file) {
+  const header = Buffer.alloc(12), fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  let size;
+  try { size = fs.readSync(fd, header, 0, header.length, 0); }
+  finally { fs.closeSync(fd); }
+  if (size >= 12 && header.toString('ascii', 0, 4) === 'RIFF' && header.toString('ascii', 8, 12) === 'WAVE') return 'audio/wav';
+  if (size >= 10 && (header.toString('ascii', 0, 3) === 'ID3' || header[0] === 0xff && (header[1] & 0xe0) === 0xe0)) return 'audio/mpeg';
+  throw new ProviderContractError('供应商音频不是可识别的 WAV 或 MP3 容器', {
+    stage: 'download', category: 'protocol', acceptance: 'accepted'
+  });
+}
+
+async function deliverArtifacts(runtime, dataRoot, taskId, adapter, remoteArtifacts, signal) {
   beginCoreDelivery(dataRoot, taskId);
   const artifactIds = [];
   const stagedFiles = [];
@@ -147,22 +190,25 @@ async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, sign
       }
       const target = stagingFile(dataRoot);
       stagedFiles.push({ target, mediaType });
-      const downloaded = await invokeProviderOperation(adapter, 'download', {
+      const downloaded = await invokeNetwork(runtime, adapter, 'download', {
         capability: task.capability,
         artifact: remote,
         targetPath: target,
         signal
-      }, { signal, taskId });
+      }, networkOperationContext(runtime, dataRoot, taskId, { signal, attemptId: task.activeAttemptId }));
       const stat = fs.lstatSync(target);
       if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== downloaded.bytes) {
         throw Object.assign(new Error('Provider 物化结果与文件证据不一致'), {
           stage: 'download', category: 'local_io', acceptance: 'accepted'
         });
       }
+      assertProviderMediaSize(stat.size, task.capability);
       const staged = stagedFiles.at(-1);
       if (task.capability === 'image') {
         staged.bytes = fs.readFileSync(target);
         staged.mediaType = await generatedImageMediaType(staged.bytes);
+      } else if (['tts', 'music'].includes(task.capability)) {
+        staged.mediaType = generatedAudioMediaType(target);
       }
     }
     recordCoreDownloadCompleted(dataRoot, taskId);
@@ -188,30 +234,34 @@ async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, sign
   }
 }
 
-async function observeWithinRoot(dataRoot, taskId, adapter, signal) {
+async function observeWithinRoot(runtime, dataRoot, taskId, adapter, signal) {
   const before = inspectCoreTask(dataRoot, taskId);
   checkAdapterForTask(before, adapter);
   activateCoreWatch(dataRoot, taskId);
   let result;
   try {
-    result = await invokeProviderOperation(adapter, 'poll', {
+    result = await invokeNetwork(runtime, adapter, 'poll', {
       capability: before.capability,
       remoteTaskId: before.remoteTaskId,
       signal
-    }, { signal, taskId });
+    }, networkOperationContext(runtime, dataRoot, taskId, { signal, attemptId: before.activeAttemptId }));
   } catch (error) {
     return recordCoreWatchError(dataRoot, taskId, error);
   }
-  const cachedFlowResult = Boolean(before.flowBinding && result.kind === 'succeeded');
-  if (cachedFlowResult) createDeliveryCache(dataRoot, before, result.artifacts);
+  let cachedFlowResult = false, cacheError;
+  if (before.flowBinding && result.kind === 'succeeded') {
+    try { createDeliveryCache(dataRoot, before, result.artifacts); cachedFlowResult = true; }
+    catch (error) { cacheError = error; }
+  }
   const recorded = recordCorePollResult(dataRoot, taskId, result, { deliveryCache: cachedFlowResult });
   if (result.kind !== 'succeeded') return recorded;
-  if (cachedFlowResult) return deliverCachedArtifacts(dataRoot, taskId, adapter, signal);
-  return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
+  if (cacheError) return failCoreDelivery(dataRoot, taskId, cacheError);
+  if (cachedFlowResult) return deliverCachedArtifacts(runtime, dataRoot, taskId, adapter, signal);
+  return deliverArtifacts(runtime, dataRoot, taskId, adapter, result.artifacts, signal);
 }
 
 /** 同步结果按已提交缓存补交付；已下载项不再访问 Provider，稳定 Artifact ID 防重复。 */
-async function deliverCachedArtifacts(dataRoot, taskId, adapter, signal) {
+async function deliverCachedArtifacts(runtime, dataRoot, taskId, adapter, signal) {
   beginCoreDelivery(dataRoot, taskId);
   try {
     const task = inspectCoreTask(dataRoot, taskId);
@@ -228,16 +278,17 @@ async function deliverCachedArtifacts(dataRoot, taskId, adapter, signal) {
         }
         checkAdapterForTask(task, adapter);
         const target = newDeliveryPayloadPath(dataRoot, cache);
-        const downloaded = await invokeProviderOperation(adapter, 'download', {
+        const downloaded = await invokeNetwork(runtime, adapter, 'download', {
           capability: task.capability, artifact: item.source, targetPath: target, signal
-        }, { signal, taskId });
+        }, networkOperationContext(runtime, dataRoot, taskId, { signal, attemptId: task.activeAttemptId }));
         const stat = fs.lstatSync(target);
         if (!stat.isFile() || stat.isSymbolicLink() || !stat.size || stat.size !== downloaded.bytes) {
           throw new Error('Provider 物化结果与文件证据不一致');
         }
+        assertProviderMediaSize(stat.size, task.capability);
         const mediaType = task.capability === 'image'
           ? await generatedImageMediaType(fs.readFileSync(target))
-          : declaredMediaType;
+          : ['tts', 'music'].includes(task.capability) ? generatedAudioMediaType(target) : declaredMediaType;
         if (!profile.mediaTypes.includes(mediaType)) throw new Error('交付媒体类型不在 Profile 白名单');
         recordDeliveryPayload(dataRoot, cache, index, target, mediaType);
       }
@@ -250,7 +301,7 @@ async function deliverCachedArtifacts(dataRoot, taskId, adapter, signal) {
       const sourcePath = readDeliveryPayload(dataRoot, cache, index);
       const mediaType = task.capability === 'image'
         ? await generatedImageMediaType(fs.readFileSync(sourcePath))
-        : (item.payload.mediaType || profile.defaultMediaType);
+        : ['tts', 'music'].includes(task.capability) ? generatedAudioMediaType(sourcePath) : (item.payload.mediaType || profile.defaultMediaType);
       if (!profile.mediaTypes.includes(mediaType)) throw new Error('交付媒体类型不在 Profile 白名单');
       const artifact = adoptCoreArtifactFile(dataRoot, {
         artifactId: item.artifactId, sourcePath, createdAt: cache.createdAt,
@@ -272,10 +323,11 @@ async function deliverCachedArtifacts(dataRoot, taskId, adapter, signal) {
  */
 export function createProviderTaskRunner(runtime) {
   checkRuntime(runtime);
-  let activeTasks = runtimeTaskGates.get(runtime);
+  const gate = runtime.taskGate || runtime;
+  let activeTasks = runtimeTaskGates.get(gate);
   if (!activeTasks) {
     activeTasks = new Set();
-    runtimeTaskGates.set(runtime, activeTasks);
+    runtimeTaskGates.set(gate, activeTasks);
   }
 
   async function runExclusive(taskId, operation, callback) {
@@ -299,6 +351,8 @@ export function createProviderTaskRunner(runtime) {
       if (signal.aborted) throw new ProviderTaskRunnerError('IRIS_PROVIDER_ABORTED', '提交已取消');
       const capability = String(input.capability || '').trim();
       let candidates = normalizedCandidates(capability, input.candidates);
+      const networkRequirement = candidates[0].networkRequirement;
+      const networkBudget = createNetworkAttemptBudget();
       let providerInput = input.providerInput ?? {};
       if (providerInput.workflow_parameters !== undefined && candidates.some(candidate => candidate.adapter.protocol !== 'comfyui')) {
         throw new ProviderTaskRunnerError('IRIS_COMFYUI_PARAMETERS_INVALID', '工作流参数仅用于明确的 ComfyUI 模板');
@@ -306,15 +360,16 @@ export function createProviderTaskRunner(runtime) {
       let flow;
       if (input.flowRunId !== undefined) {
         flow = readFlowRun(dataRoot, input.flowRunId);
-        const audio = isAudioRecipe(flow.recipe), normalized = audio ? normalizeAudioFlowInput(flow.recipe, flow.input) : null;
-        const expected = audio ? Object.fromEntries(Object.entries(normalized).filter(([key]) => key !== 'model_ref')) : normalizeGenerationInput('image', flow.input).providerInput;
-        const expectedCapability = audio ? flow.recipe === 'speech/v0' ? 'tts' : 'transcribe' : 'image';
+        const audio = isAudioRecipe(flow.recipe), video = flow.recipe === 'video-generate/v0';
+        const expected = audio ? Object.fromEntries(Object.entries(normalizeAudioFlowInput(flow.recipe, flow.input)).filter(([key]) => key !== 'model_ref'))
+          : normalizeGenerationInput(video ? 'video' : 'image', flow.input).providerInput;
+        const expectedCapability = video ? 'video' : audio ? flow.recipe === 'speech/v0' ? 'tts' : 'transcribe' : 'image';
         if (capability !== expectedCapability || !flowStep(flow).claimed || input.sourceArtifactId !== flow.source?.artifactId
             || Object.keys(providerInput).length !== Object.keys(expected).length
             || Object.keys(expected).some(key => key === 'workflow_parameters'
               ? JSON.stringify(providerInput[key]) !== JSON.stringify(expected[key]) : providerInput[key] !== expected[key])
             || candidates.length !== 1 || candidates[0].model !== flow.input.model_ref
-            || candidates[0].providerBinding !== flow.providerBinding) {
+            || candidates[0].providerBinding !== flow.providerBinding || !sameNetworkRequirement(networkRequirement, flow.networkRequirement)) {
           flowFail('IRIS_FLOW_INPUT_CONFLICT', '提交与流程已保存的输入或模型绑定冲突');
         }
       }
@@ -324,9 +379,15 @@ export function createProviderTaskRunner(runtime) {
         providerInput = { ...providerInput, image };
       }
       if (input.sourceArtifactId !== undefined && !['image', 'transcribe'].includes(capability)) throw new TypeError('来源作品仅用于图片编辑或转写');
+      if (runtime.scheduler) await runtime.scheduler.beforeSubmit(runtime, dataRoot, { modelRef: candidates[0].model },
+        () => candidates[0].adapter.schedulingReadyAt?.(candidates[0].providerModel));
       const task = flow ? claimFlowTask(dataRoot, flow.id)
-        : createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId });
+        : createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId,
+          ...(networkRequirement ? { networkRequirement } : {}) });
       if (flow && task.attempts.length) flowFail('IRIS_FLOW_TASK_ALREADY_STARTED', '该流程 Task 已有提交意图，禁止重新 submit');
+      if (activeTasks.has(task.id)) throw new ProviderTaskRunnerError('IRIS_PROVIDER_TASK_BUSY', '该 Task 已有生命周期操作正在执行');
+      activeTasks.add(task.id);
+      try {
       const completedResults = new Map();
       const wrapped = candidates.map(({ adapter, model, providerModel, prepareInput }) => ({
         id: adapter.id,
@@ -334,17 +395,22 @@ export function createProviderTaskRunner(runtime) {
         adapter,
         submit: async (providerInput, context) => {
           if (prepareInput) {
-            try { providerInput = await prepareInput({ providerInput, signal }); }
+            try {
+              const prepareContext = networkOperationContext(runtime, dataRoot, task.id, { providerInput, signal, attempt: context.attempt, attemptId: context.attempt.id, networkBudget });
+              const prepare = () => prepareInput(prepareContext);
+              providerInput = await (runtime.networkWait ? runtime.networkWait(prepare, 'prepareInput') : prepare());
+            }
             catch (error) { throw new ProviderContractError((capability === 'video' ? '视频' : '音频') + '输入准备失败：' + (error.safeMessage || error.message), {
               ...providerErrorRecord(error), stage: error.stage || 'prepare', category: error.category || 'local_io', acceptance: 'not_accepted'
             }); }
           }
           if (signal.aborted) throw new ProviderContractError('提交已取消', { stage: 'prepare', category: 'aborted', acceptance: 'not_accepted' });
-          const result = await invokeProviderOperation(
+          const result = await invokeNetwork(
+            runtime,
             adapter,
             'submit',
             { capability, model: providerModel, input: providerInput, signal },
-            { ...context, signal, taskId: task.id }
+            networkOperationContext(runtime, dataRoot, task.id, { ...context, signal, attemptId: context.attempt.id, networkBudget })
           );
           if (result.kind === 'completed') completedResults.set(context.attempt.id, result.artifacts);
           return result;
@@ -354,9 +420,12 @@ export function createProviderTaskRunner(runtime) {
         signal,
         beforeAttempt: async (attempt) => {
           const candidate = candidates[attempt.ordinal - 1];
+          if (attempt.ordinal > 1 && runtime.scheduler) await runtime.scheduler.beforeSubmit(runtime, dataRoot, { modelRef: candidate.model },
+            () => candidate.adapter.schedulingReadyAt?.(candidate.providerModel));
           return beginCoreAttempt(dataRoot, task.id, {
             ...attempt,
             ...(candidate.providerBinding !== undefined ? { providerBinding: candidate.providerBinding } : {}),
+            ...(candidate.networkRequirement ? { networkRequirement: candidate.networkRequirement } : {}),
             ...(candidate.pluginDependency ? { pluginDependency: candidate.pluginDependency } : {}),
             ...(candidate.selectionReason !== undefined ? { selectionReason: candidate.selectionReason } : {})
           });
@@ -385,7 +454,7 @@ export function createProviderTaskRunner(runtime) {
       } else if (submitted.result.kind === 'completed') {
         return Object.freeze({
           taskId: task.id,
-          task: await deliverCachedArtifacts(dataRoot, task.id, submitted.candidate.adapter, signal),
+          task: await deliverCachedArtifacts(runtime, dataRoot, task.id, submitted.candidate.adapter, signal),
           attempts: submitted.attempts
         });
       }
@@ -394,6 +463,7 @@ export function createProviderTaskRunner(runtime) {
         task: inspectCoreTask(dataRoot, task.id),
         attempts: submitted.attempts
       });
+      } finally { activeTasks.delete(task.id); }
     });
   }
 
@@ -408,7 +478,7 @@ export function createProviderTaskRunner(runtime) {
         checkAdapterForTask(current, adapter);
         if (current.watchState === 'active') recoverCoreTask(dataRoot, taskId);
       }
-      return observeWithinRoot(dataRoot, taskId, adapter, signal);
+      return observeWithinRoot(runtime, dataRoot, taskId, adapter, signal);
     });
   }
 
@@ -417,14 +487,14 @@ export function createProviderTaskRunner(runtime) {
       const task = inspectCoreTask(dataRoot, taskId);
       if (adapter || !task.deliveryCache) checkAdapterForTask(task, adapter);
       prepareCoreRedelivery(dataRoot, taskId);
-      if (task.deliveryCache) return deliverCachedArtifacts(dataRoot, taskId, adapter, signal);
+      if (task.deliveryCache) return deliverCachedArtifacts(runtime, dataRoot, taskId, adapter, signal);
       let result;
       try {
-        result = await invokeProviderOperation(adapter, 'poll', {
+        result = await invokeNetwork(runtime, adapter, 'poll', {
           capability: task.capability,
           remoteTaskId: task.remoteTaskId,
           signal
-        }, { signal, taskId, redelivery: true });
+        }, networkOperationContext(runtime, dataRoot, taskId, { signal, attemptId: task.activeAttemptId, redelivery: true }));
       } catch (error) {
         return failCoreDelivery(dataRoot, taskId, error);
       }
@@ -434,7 +504,7 @@ export function createProviderTaskRunner(runtime) {
           { stage: 'download', category: 'protocol', acceptance: 'accepted' }
         ));
       }
-      return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
+      return deliverArtifacts(runtime, dataRoot, taskId, adapter, result.artifacts, signal);
     });
   }
 
@@ -446,23 +516,26 @@ export function createProviderTaskRunner(runtime) {
       if (!hasProviderOperation(adapter, 'cancel')) {
         return recordCoreCancelResult(dataRoot, taskId, { kind: 'not_supported' });
       }
-      const result = await invokeProviderOperation(adapter, 'cancel', {
+      const result = await invokeNetwork(runtime, adapter, 'cancel', {
         capability: task.capability,
         remoteTaskId: task.remoteTaskId,
         signal
-      }, { signal, taskId });
+      }, networkOperationContext(runtime, dataRoot, taskId, { signal, attemptId: task.activeAttemptId }));
       return recordCoreCancelResult(dataRoot, taskId, result);
     });
   }
 
   function recover(taskId, adapter) {
     return runExclusive(taskId, 'recover', async ({ dataRoot, signal }) => {
+      const before = inspectCoreTask(dataRoot, taskId);
+      if (before.acceptance === 'accepted' && before.remoteTaskId && before.outcome === 'none'
+          && ['accepted', 'running'].includes(before.phase)) checkAdapterForTask(before, adapter);
       const recovered = recoverCoreTask(dataRoot, taskId);
       if (recovered.acceptance === 'accepted' && recovered.remoteTaskId
           && recovered.outcome === 'none'
           && ['accepted', 'running'].includes(recovered.phase)) {
         checkAdapterForTask(recovered, adapter);
-        return observeWithinRoot(dataRoot, taskId, adapter, signal);
+        return observeWithinRoot(runtime, dataRoot, taskId, adapter, signal);
       }
       return recovered;
     });
@@ -475,6 +548,9 @@ export function createProviderTaskRunner(runtime) {
     observe,
     redeliver,
     cancel,
-    recover
+    recover,
+    assertIdle(taskId) {
+      if (activeTasks.has(taskId)) throw new ProviderTaskRunnerError('IRIS_PROVIDER_TASK_BUSY', '该 Task 已有生命周期操作正在执行');
+    }
   });
 }

package/lib/provider-transport.js

@@ -0,0 +1,16 @@
+// Bind all hops of an existing media transport to an instance-owned request function.
+import * as transport from './adapters.js';
+
+const REQUEST_METHODS = Object.freeze([
+  'generateImageMultimodal', 'startImageGeneration', 'submitImage', 'submitVideo', 'uploadTempFile',
+  'pollTask', 'synthesizeTts', 'openAiGenerateImage', 'openAiChatGenerateImage', 'openAiResponsesGenerateImage',
+  'listModels', 'visionStream', 'submitTranscription', 'pollTranscriptionTask', 'generateMusic'
+]);
+
+export function createProviderTransport(fetchPort) {
+  if (typeof fetchPort !== 'function') throw new TypeError('Provider transport 需要明确的 fetchPort');
+  const bound = { ...transport };
+  for (const name of REQUEST_METHODS) bound[name] = input => transport[name]({ ...input, fetchPort });
+  bound.downloadTo = (url, filePath, options) => transport.downloadTo(url, filePath, { ...options, fetchPort });
+  return Object.freeze(bound);
+}