@mokuyoaxis/dsh-iris 0.2.5 → 0.2.7

package/lib/index.js

@@ -18,7 +18,9 @@ import { runVisionRequest, readVisionImageFile } from './vision-model-routing.js
 import { waitForModelWork } from './model-call-runtime.js';
 import { hasHostPort, requireHostPort } from './host-contract.js';
 import { createDshHostAdapter } from './dsh-host-adapter.js';
-import { cropForDsh, diffForDsh, framesForDsh, summaryFramesForDsh, visionImageForDsh, htmlForDsh, inspectProviderTaskForDsh, projectCoreTaskForDsh, readCoreArtifactMediaForDsh, resumeProviderTaskWatchesForDsh, stopProviderTaskWatchesForDsh } from './dsh-core-adapter.js';
+import { withDshProviderConfig } from './dsh-provider-config.js';
+import { createDshRuntime, dshCoreDataRoot } from './dsh-core-adapter.js';
+import { ModelPortError } from './model-port-contract.js';
 import { imageDimensions } from './pixels.js';
 import { runLocateRequest, runSummaryRequest, describeGeneratedImage } from './composite-vision-routing.js';
 import { normalizeSummarySource, summaryFrameRecords, summaryTimelineLabel } from './summary-input.js';
@@ -64,12 +66,11 @@ function outputDir() {
 
 /* ---------------- 媒体路由：/iris/media/:taskId/:token/:name ---------------- */
 
-let mediaRouteMounted = false;
-function mountIrisRoutes(routeCtx) {
+function mountIrisRoutes(routeCtx, core, routes) {
   // Cordis 服务只在 DSH 宿主边界探测；Command 与通用工具辅助函数不接收原始 ctx
   const host = dshHost(routeCtx);
   const reg = hasHostPort(host, 'routes') ? host.ports.routes : undefined;
-  if (!reg || typeof reg.register !== 'function' || mediaRouteMounted) return;
+  if (!reg || typeof reg.register !== 'function' || routes.mounted) return;
   try {
     const disposeMedia = reg.register({
       kind: 'prefix',
@@ -79,21 +80,21 @@ function mountIrisRoutes(routeCtx) {
     const disposeApi = reg.register({
       kind: 'prefix',
       path: '/iris/api',
-      handler: guarded((req, res) => serveApi(req, res, dshHost(routeCtx)))
+      handler: guarded((req, res) => serveApi(req, res, dshHost(routeCtx), core))
     });
     const disposeRender = reg.register({
       kind: 'prefix',
       path: '/iris/render',
       handler: guarded(serveRender)
     });
-    mediaRouteMounted = true;
+    routes.mounted = true;
     recordHostRoutes(EXPECTED_IRIS_ROUTES);
     routeCtx.effect(() => () => {
       if (typeof disposeMedia === 'function') disposeMedia();
       if (typeof disposeApi === 'function') disposeApi();
       if (typeof disposeRender === 'function') disposeRender();
       closeAllSse(); // SSE 长连接随插件停用一起关闭，不留悬挂连接
-      mediaRouteMounted = false;
+      routes.mounted = false;
     }, 'iris: media+api+actions+render routes');
     console.log('[iris] 媒体+工作台+操作路由已挂载：/iris/media · /iris/api · /iris/api/actions · /iris/render');
   } catch (err) {
@@ -179,11 +180,11 @@ function coreTaskTerminalProblem(task, label = '任务') {
   return label + '需要人工处理';
 }
 
-async function awaitCoreTerminal(taskId, { timeoutMs, signal }) {
+async function awaitCoreTerminal(core, taskId, { timeoutMs, signal }) {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
     if (signal?.aborted) throw new Error('已取消；Core 任务仍保留远端受理事实，可稍后查询');
-    const task = await inspectProviderTaskForDsh(taskId, { signal });
+    const task = await core.inspectProviderTaskForDsh(taskId, { signal });
     if (coreTaskWaitFinished(task)) return task;
     if (Date.now() > deadline) return null;
     await new Promise((resolve) => setTimeout(resolve, 1000));
@@ -219,6 +220,14 @@ function safeRegister(host, definition) {
 
 export async function apply(ctx) {
   beginHostRuntime({ pluginId: IRIS_PLUGIN_ID, version: PACKAGE_VERSION });
+  const core = createDshRuntime({ dataRoot: dshCoreDataRoot(), getHost: () => dshHost(ctx) });
+  ctx.provide('irisRuntime', core);
+  const routes = { mounted: false };
+  const { cropForDsh, diffForDsh, framesForDsh, summaryFramesForDsh, visionImageForDsh, htmlForDsh, inspectProviderTaskForDsh, projectCoreTaskForDsh, readCoreArtifactMediaForDsh, resumeProviderTaskWatchesForDsh } = core;
+  ctx.effect(() => () => {
+    tasks.stopWatchAll();
+    return core.dispose();
+  }, 'iris: DSH runtime');
   guard('Iris 私有存储权限收紧', () => hardenPrivateTree(store.irisHome()));
 
   guard('上传临时文件清理', () => purgeStaleUploads());
@@ -242,26 +251,18 @@ export async function apply(ctx) {
     if (resumed.length) console.log(`[iris] 已恢复接管 ${resumed.length} 个后台任务`);
   });
 
-  try {
-    const resumed = await resumeProviderTaskWatchesForDsh();
-    if (resumed.length) console.log(`[iris] 已恢复接管 ${resumed.length} 个 Core 图片任务`);
-  } catch (error) {
-    console.error('[iris] 恢复 Core 图片后台任务失败（已隔离，不影响宿主）:', error?.message || error);
-  }
-
-  // Fiber 清理：插件停用/更新时停掉 legacy 与 Core 的全部 Host 盯守句柄
-  guard('盯守句柄注册', () => {
-    ctx.effect(() => () => {
-      tasks.stopWatchAll();
-      stopProviderTaskWatchesForDsh();
-    });
+  // Owned background setup lets unload cancel a slow connection resolver during takeover.
+  void resumeProviderTaskWatchesForDsh().then(resumed => {
+    if (resumed.length) console.log('[iris] 已恢复接管 ' + resumed.length + ' 个 Core 媒体任务');
+  }, error => {
+    if (core.snapshot().state === 'open') console.error('[iris] 恢复 Core 后台任务失败:', error?.code || 'unknown');
   });
 
   // 媒体路由（视频/音频在对话流里的可播通路；图片仍走原生附件）
-  ctx.inject(['webServer'], mountIrisRoutes);
-  ctx.inject(['httpServer'], mountIrisRoutes);
+  ctx.inject(['webServer'], routeCtx => mountIrisRoutes(routeCtx, core, routes));
+  ctx.inject(['httpServer'], routeCtx => mountIrisRoutes(routeCtx, core, routes));
   // 若 webServer 已在运行，inject 回调也会触发；这里兜底立即挂载一次
-  guard('媒体路由兜底挂载', () => mountIrisRoutes(ctx));
+  guard('媒体路由兜底挂载', () => mountIrisRoutes(ctx, core, routes));
 
   // DSH 的 Skill registry 是可选宿主能力。存在时把 npm 包内三项 Skill 注册到
   // 全局层；项目目录中的同名 Skill 仍由 DSH 原生优先级覆盖。
@@ -274,6 +275,29 @@ export async function apply(ctx) {
   });
 
   const host = dshHost(ctx);
+  const providerTools = new Set(['iris_draw_image', 'iris_edit_image', 'iris_generate_video', 'iris_generate_music',
+    'iris_speak_text', 'iris_transcribe_audio', 'iris_look_at_image', 'iris_relook_attachment',
+    'iris_media_summarize', 'iris_locate', 'iris_long_ocr']);
+  const visionTools = new Set(['iris_look_at_image', 'iris_relook_attachment', 'iris_media_summarize', 'iris_locate', 'iris_long_ocr']);
+  function registerIrisTool(definition) {
+    safeRegister(host, { ...definition, execute(args, exec = {}) {
+      const owned = structuredClone(args || {});
+      return core.runHostOperation(signal => {
+        const execute = async () => {
+          if (visionTools.has(definition.name) && !owned.model) await store.refreshAutomaticDirectories({ capability: 'vision', signal });
+          signal.throwIfAborted();
+          return definition.execute(owned, { ...exec, signal });
+        };
+        return providerTools.has(definition.name)
+          ? withDshProviderConfig(dshHost(ctx), execute, { signal }) : execute();
+      }, { signal: exec.signal }).catch(error => {
+        if (visionTools.has(definition.name) && exec.signal?.aborted && error === exec.signal.reason) {
+          throw new ModelPortError('IRIS_MODEL_ABORTED');
+        }
+        throw error;
+      });
+    } });
+  }
   if (!hasHostPort(host, 'tools')) {
     console.error('[iris] tools 服务不可用，跳过全部工具注册（宿主不受影响）');
     return;
@@ -281,7 +305,7 @@ export async function apply(ctx) {
 
   async function coreImageToolResult(submitted, prompt, signal) {
     let final = await inspectProviderTaskForDsh(submitted.taskId, { signal });
-    if (!coreTaskWaitFinished(final)) final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, signal });
+    if (!coreTaskWaitFinished(final)) final = await awaitCoreTerminal(core, submitted.taskId, { timeoutMs: AWAIT_MS.image, signal });
     if (!final) return { blocks: [{ type: 'text', text: `[iris] Core 图片任务仍在后台观察（task: ${submitted.taskId}）。稍后可用 iris_task_status 查询进度与 Artifact。` }] };
     const terminalProblem = coreTaskTerminalProblem(final, '图像生成');
     if (terminalProblem) throw new Error(terminalProblem);
@@ -291,7 +315,7 @@ export async function apply(ctx) {
     let note = '';
     try {
       const described = await describeGeneratedImage(dshHost(ctx), {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, originalPrompt: prompt, signal,
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, originalPrompt: prompt, signal,
         async prepareImage(inputSignal) {
           const first = await readCoreArtifactMediaForDsh(projected.artifacts[0].artifact.id, { signal: inputSignal });
           return { bytes: new Uint8Array(first.bytes), mediaType: first.artifact.mediaType };
@@ -309,7 +333,7 @@ export async function apply(ctx) {
     return { blocks };
   }
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_import_image',
     description: 'Save a local image or a current-session image attachment as a persistent Iris image Artifact for later viewing, editing and export. Provide exactly one of image_path or attachment_id. Supports static PNG/JPEG/WebP up to 20 MiB, preserves the source, and never calls a model.',
     parameters: {
@@ -327,14 +351,14 @@ export async function apply(ctx) {
       const attachmentId = String(args.attachment_id || '').trim();
       if (Boolean(imagePath) === Boolean(attachmentId)) throw new Error('图片导入须选择image_path或attachment_id之一');
       const input = imagePath ? { image_path: imagePath } : {
-        image_bytes: (await resolveVisionImageInput(dshHost(ctx), exec, { attachment_id: attachmentId }, exec.signal)).bytes
+        image_bytes: (await resolveVisionImageInput(core, dshHost(ctx), exec, { attachment_id: attachmentId }, exec.signal)).bytes
       };
-      return runAction(dshHost(ctx), 'image_import', input, { signal: exec.signal });
+      return runAction(dshHost(ctx), 'image_import', input, { signal: exec.signal, core });
     }
   });
 
   /* ---------- 🖼️ 画图 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_draw_image',
     description:
       'Generate an image from a detailed prompt using the user-configured image model and its configured image protocol. ' +
@@ -345,7 +369,7 @@ export async function apply(ctx) {
         prompt: { type: 'string', description: 'Detailed visual description of the image to create' },
         size: { type: 'string', description: "Output size; DashScope uses 'W*H' (e.g. '1024*1024'), OpenAI uses 'WxH'. Default provider default." },
         n: { type: 'string', description: "Number of images, default '1'" },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id also accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled function pool; selects only this item (legacy bare model id also accepted)' }
       },
       required: ['prompt']
     },
@@ -356,7 +380,7 @@ export async function apply(ctx) {
     isConcurrencySafe: () => false,
     async execute(args, exec) {
       const prompt = String(args.prompt || '').trim();
-      const submitted = await runAction(dshHost(ctx), 'image', args, { signal: exec.signal });
+      const submitted = await runAction(dshHost(ctx), 'image', args, { signal: exec.signal, core });
       if (submitted.storage === 'core') {
         return coreImageToolResult(submitted, prompt, exec.signal);
       }
@@ -390,7 +414,7 @@ export async function apply(ctx) {
       let note = '';
       try {
         const described = await describeGeneratedImage(dshHost(ctx), {
-          providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, originalPrompt: prompt, signal: exec.signal,
+          providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, originalPrompt: prompt, signal: exec.signal,
           prepareImage: signal => readVisionImageFile(files[0], MEDIA_TYPES[path.extname(files[0]).toLowerCase()] || 'image/png', signal)
         });
         if (described) note = `画面内容：${described}`;
@@ -405,27 +429,27 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_edit_image',
-    description: 'Edit an existing Core image by Artifact ID and an instruction using an assigned chat-image model or native DashScope Qwen edit model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
+    description: 'Edit an existing Core image by Artifact ID and an instruction using an allowed chat-image model or native DashScope Qwen edit model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
     parameters: {
       type: 'object', properties: {
         source_artifact_id: { type: 'string', description: 'Core Artifact ID of the source PNG, JPEG or WebP image (up to 20 MiB)' },
         prompt: { type: 'string', description: 'Describe the changes and what should be preserved in the source image' },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item; supports openai-chat-images or DashScope Qwen edit/max/plus and 2.0/pro models' },
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled image pool; selects only this item; supports openai-chat-images or DashScope Qwen edit/max/plus and 2.0/pro models' },
         n: { type: 'string', description: "Number of images, default '1'" }
       }, required: ['source_artifact_id', 'prompt']
     },
     output: { schema: { type: 'object' }, render: (_args, value) => value.blocks },
     isConcurrencySafe: () => false,
     async execute(args, exec) {
-      const submitted = await runAction(dshHost(ctx), 'image_edit', args, { signal: exec.signal });
+      const submitted = await runAction(dshHost(ctx), 'image_edit', args, { signal: exec.signal, core });
       return coreImageToolResult(submitted, String(args.prompt || '').trim(), exec.signal);
     }
   });
 
   /* ---------- 🎬 视频生成 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_generate_video',
     description:
       'Generate a video with the configured DashScope video model. Three modes: ' +
@@ -443,18 +467,18 @@ export async function apply(ctx) {
         resolution: { type: 'string', description: "s2v only: output tier '480P' (default) or '720P'" },
         size: { type: 'string', description: "t2v/i2v only: output size 'W*H', e.g. '1280*720' (default)" },
         duration: { type: 'number', description: 't2v/i2v only: duration in seconds, if the model supports it' },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled function pool; selects only this item (legacy bare model id accepted)' }
       },
       required: []
     },
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => false,
     async execute(args, exec) {
-      const submitted = await runAction(dshHost(ctx), 'video', { ...args, session_id: exec.agent?.session?.id }, { signal: exec.signal });
+      const submitted = await runAction(dshHost(ctx), 'video', { ...args, session_id: exec.agent?.session?.id }, { signal: exec.signal, core });
       if (submitted.storage === 'core') {
         let final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
         if (!coreTaskWaitFinished(final)) {
-          final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.video, signal: exec.signal });
+          final = await awaitCoreTerminal(core, submitted.taskId, { timeoutMs: AWAIT_MS.video, signal: exec.signal });
         }
         if (!final) {
           return `[iris] Core 视频任务已提交并转入后台观察（task: ${submitted.taskId}，remoteTask: ${submitted.remoteTaskId}）。\n` +
@@ -487,12 +511,12 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_generate_music',
-    description: 'Generate music using a model explicitly assigned to Music. Returns audio artifact IDs and playback links. Lyrics, vocals and duration are prompt intentions. Configured 502 retries may generate again.',
+    description: 'Generate music using a model in the enabled Music pool. Returns audio artifact IDs and playback links. Lyrics, vocals and duration are prompt intentions. Configured 502 retries may generate again.',
     parameters: { type: 'object', properties: {
       prompt: { type: 'string', description: 'Describe the music, including any lyrics, vocals, mood or intended duration' },
-      model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item' },
+      model: { type: 'string', description: 'Optional providerId::modelId in the enabled Music pool; selects only this item' },
       timeout_ms: { type: 'integer', description: 'Per-attempt timeout; default 300000 ms' },
       retry_502: { type: 'integer', description: '502 regeneration retries, 0–5; default 2; each retry consumes another request' },
       retry_delay_ms: { type: 'integer', description: 'Delay between 502 retries; default 5000 ms' }
@@ -500,14 +524,14 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
-      const submitted = await runAction(dshHost(ctx), 'music', args, { signal: exec.signal });
+      const submitted = await runAction(dshHost(ctx), 'music', args, { signal: exec.signal, core });
       return submitted.text + '\nartifact: ' + submitted.artifactIds.join(', ') + '\n' +
         submitted.artifactIds.map(id => '[♪ 音乐播放](/iris/api/core/artifact/' + encodeURIComponent(id) + '/media)').join('\n');
     }
   });
 
   /* ---------- 🔊 语音合成 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_speak_text',
     description: 'Synthesize spoken audio from text using the configured TTS model. Returns Core audio Artifact IDs and playback links; export an Artifact to a host file before passing it as audio_path to another tool. Use iris_generate_music for songs or background music.',
     parameters: {
@@ -515,14 +539,14 @@ export async function apply(ctx) {
       properties: {
         text: { type: 'string', description: 'Text to speak' },
         voice: { type: 'string', description: "Voice name, e.g. 'Cherry' (DashScope qwen-tts voices)" },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled function pool; selects only this item (legacy bare model id accepted)' }
       },
       required: ['text']
     },
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
-      const submitted = await runAction(dshHost(ctx), 'tts', args, { signal: exec.signal });
+      const submitted = await runAction(dshHost(ctx), 'tts', args, { signal: exec.signal, core });
       if (submitted.storage === 'core') {
         const final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
         const terminalProblem = coreTaskTerminalProblem(final, '语音合成');
@@ -545,25 +569,25 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎙️ 音频转写（阶段 7.2） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_transcribe_audio',
     description: 'Transcribe an audio file (wav/mp3) to text using the configured DashScope provider (qwen-audio-3.0-asr-flash-filetrans). The audio is uploaded to Bailian temp storage, then an async task is submitted. Returns the full recognized text.',
     parameters: {
       type: 'object',
       properties: {
         audio_path: { type: 'string', description: 'Absolute path to the audio file (wav/mp3)' },
-        model: { type: 'string', description: 'Optional assigned transcription providerId::modelId; selects only this item (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled transcription pool; selects only this item (legacy bare model id accepted)' }
       },
       required: ['audio_path']
     },
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => false,
     async execute(args, exec) {
-      const submitted = await runAction(dshHost(ctx), 'transcribe', args, { signal: exec.signal });
+      const submitted = await runAction(dshHost(ctx), 'transcribe', args, { signal: exec.signal, core });
       if (submitted.storage === 'core') {
         let final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
         if (!coreTaskWaitFinished(final)) {
-          final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.transcribe, signal: exec.signal });
+          final = await awaitCoreTerminal(core, submitted.taskId, { timeoutMs: AWAIT_MS.transcribe, signal: exec.signal });
         }
         if (!final) {
           return `[iris] Core 转写任务已提交并转入后台观察（task: ${submitted.taskId}）。完成后用 iris_task_status 查询进度与 Artifact。`;
@@ -588,7 +612,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎞️ 视频抽帧（阶段 7.1，ffmpeg 可选） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_video_frames',
     description:
       'Extract N frames (uniformly sampled across the video) from a local video file using the system ffmpeg. ' +
@@ -646,7 +670,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📝 多模态视频摘要（阶段 7.3，ffmpeg 可选） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_media_summarize',
     description:
       'Summarize a local video or existing Core video-frame Artifacts as one contact sheet (with timestamps) plus an optional ' +
@@ -664,7 +688,7 @@ export async function apply(ctx) {
         target_width: { type: 'integer', description: 'Frame width for sampling (default 640)' },
         transcribe: { type: 'boolean', description: 'Auto-transcribe the audio track for video_path (default true unless transcribe_text is provided). Existing frames only consume explicit text.' },
         transcribe_text: { type: 'string', description: 'Optional existing transcript text; does not create a transcription task' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -679,7 +703,7 @@ export async function apply(ctx) {
         if (!ffmpegAvailable()) throw new Error('iris: ffmpeg 不可用，无法分析视频（可选安装 ffmpeg/ffprobe 后启用）');
       }
       const { answer, via, model, sheet, meta, frames, transcriptNote } = await runSummaryRequest(dshHost(ctx), {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, model: args.model, question: args.question, signal: exec.signal,
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, model: args.model, question: args.question, signal: exec.signal,
         async prepareMedia(signal) {
           if (source === 'core-artifacts') {
             return { ...await summaryFramesForDsh({ frameArtifactIds: args.frame_artifact_ids, signal }), transcript: args.transcribe_text };
@@ -696,8 +720,8 @@ export async function apply(ctx) {
               try {
                 const audio = await extractAudioTrack({ inputPath: p, signal });
                 try {
-                  const submitted = await runAction(dshHost(ctx), 'transcribe', { audio_path: audio.filePath }, { signal });
-                  const final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: 120000, signal });
+                  const submitted = await runAction(dshHost(ctx), 'transcribe', { audio_path: audio.filePath }, { signal, core });
+                  const final = await awaitCoreTerminal(core, submitted.taskId, { timeoutMs: 120000, signal });
                   if (final?.outcome === 'succeeded' && final.deliveryState === 'ready') {
                     const texts = [];
                     for (const artifactId of final.artifactIds) {
@@ -745,7 +769,7 @@ export async function apply(ctx) {
 
   /* ---------- 👁 视觉路由（M3）：显式工具，自持栈为主 ---------- */
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_look_at_image',
     description:
       'Look at a local image file or an existing Core image Artifact and answer one question with the configured vision model (self-hosted provider stack, then DSH default vision). Provide exactly one of image_path or artifact_id. Local files are saved as durable DSH attachments; Core images are read directly without export or Core writes.',
@@ -755,7 +779,7 @@ export async function apply(ctx) {
         image_path: { type: 'string', description: 'Absolute path to the image file (png/jpg/jpeg/webp)' },
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path)' },
         question: { type: 'string', description: 'Question or extraction request about the image; defaults to a detailed description' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -784,7 +808,7 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_relook_attachment',
     description:
       'Ask a NEW question about an image that was already seen in this session: pass its attachment_id (from user uploads, tool results, or any iris-generated image). Pixels are re-read via the vision model.',
@@ -793,7 +817,7 @@ export async function apply(ctx) {
       properties: {
         attachment_id: { type: 'string', description: 'The attachment_id of an image that appeared in this session or was generated by iris' },
         question: { type: 'string', description: 'New question about the image pixels' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['attachment_id', 'question']
     },
@@ -820,7 +844,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📋 任务查询 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_task_status',
     description:
       'Query Iris tasks (image/video/tts/music/transcription). Pass a task_id for one task, or omit it to list recent tasks. Core results provide Artifact IDs and playback links; legacy tasks may provide file paths. Querying does not re-observe or redeliver a task.',
@@ -834,13 +858,13 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => true,
     async execute(args) {
-      const result = await runAction(dshHost(ctx), 'status', args || {});
+      const result = await runAction(dshHost(ctx), 'status', args || {}, { core });
       return result.text;
     }
   });
 
   /* ---------- ✂️ 确定性像素工具（阶段 2） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_crop',
     description:
       'Crop a rectangular region from an image (absolute local path or a session attachment_id) and save the result as a durable DSH attachment. ' +
@@ -890,7 +914,7 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_pixel_diff',
     description:
       'Compute a pixel-level difference between two images (absolute local paths or session attachment_ids). ' +
@@ -945,7 +969,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📍 模型驱动定位（阶段 3A） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_locate',
     description:
       'Locate an object/region described by `target` in an image (exactly one of absolute image_path, Core artifact_id, or session attachment_id), ' +
@@ -958,7 +982,7 @@ export async function apply(ctx) {
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path or attachment_id)' },
         attachment_id: { type: 'string', description: 'Session attachment id of an image (alternative to image_path)' },
         target: { type: 'string', description: 'The object or UI element to locate, e.g. "send button"' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['target']
     },
@@ -966,8 +990,8 @@ export async function apply(ctx) {
     isConcurrencySafe: () => true,
     async execute(args, exec) {
       const r = await runLocateRequest(dshHost(ctx), {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, model: args.model, target: args.target,
-        prepareImage: signal => resolveVisionImageInput(dshHost(ctx), exec, args, signal), signal: exec.signal
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, model: args.model, target: args.target,
+        prepareImage: signal => resolveVisionImageInput(core, dshHost(ctx), exec, args, signal), signal: exec.signal
       });
       const { width, height } = r;
       const sourceNote = args.artifact_id ? `\nCore Artifact: ${args.artifact_id}` : '';
@@ -980,7 +1004,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🖼️ HTML 截图（阶段 3C，基于 dsh-builtin-browser） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_html_screenshot',
     description:
       'Render an HTML string to a page screenshot using the shared browser. ' +
@@ -1033,7 +1057,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📄 长截图 OCR（阶段 3B，视觉模型分块） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_long_ocr',
     description:
       'OCR a (possibly long) image from exactly one of image_path, Core artifact_id, or session attachment_id: slice it into chunks (1200px tall with 120px overlap by default) ' +
@@ -1055,8 +1079,8 @@ export async function apply(ctx) {
     async execute(args, exec) {
       const host = dshHost(ctx);
       const result = await runOcrRequest(host, {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit,
-        prepareImage: operationSignal => resolveVisionImageInput(host, exec, args, operationSignal),
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability,
+        prepareImage: operationSignal => resolveVisionImageInput(core, host, exec, args, operationSignal),
         chunkHeight: args.chunk_height,
         overlap: args.overlap,
         signal: exec.signal
@@ -1115,10 +1139,10 @@ async function resolveImageInput(host, exec, { image_path, attachment_id }) {
 }
 
 /** 视觉解引用在整体预算内；路径限额读，Host 会话/附件等待可取消。 */
-async function resolveVisionImageInput(host, exec, input, signal) {
+async function resolveVisionImageInput(core, host, exec, input, signal) {
   const source = normalizeVisionImageSource(input, { allowAttachment: true });
   const { image_path, artifact_id, attachment_id } = input;
-  if (source === 'artifact_id') return visionImageForDsh({ artifactId: artifact_id, signal });
+  if (source === 'artifact_id') return core.visionImageForDsh({ artifactId: artifact_id, signal });
   if (image_path) {
     const file = String(image_path).trim();
     const mediaType = MEDIA_TYPES[path.extname(file).toLowerCase()];
@@ -1180,7 +1204,8 @@ export async function sessionAttachmentRef(host, exec, attachmentId) {
  */
 export async function askVision(host, { question, dataUrl, image, prepareImage, signal, model, budget }) {
   const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION);
-  return runVisionRequest(host, { providers: visionProviders, model, question, dataUrl, image, prepareImage, signal, budget, onRateLimit: store.recordRateLimit });
+  return runVisionRequest(host, { providers: visionProviders, model, question, dataUrl, image, prepareImage, signal, budget,
+    onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability });
 }
 
 /**

package/lib/local-api-projection.js

@@ -0,0 +1,27 @@
+// HTTP DTOs whitelist existing Core facts; never expose records or configuration wholesale.
+const STATUSES = new Set(['not_started', 'running', 'needs_attention', 'delivery_failed',
+  'needs_comparison', 'awaiting_selection', 'selected']);
+
+export function projectLocalApiFlow(facts) {
+  if (facts.contractVersion !== 0 || facts.run.recipe !== 'image-edit/v0' || !STATUSES.has(facts.status)) {
+    throw new TypeError('不支持的流程契约或状态');
+  }
+  const { run, task } = facts;
+  const ref = value => value ? { artifactId: value.artifactId } : null;
+  return {
+    contractVersion: 0, id: run.id, recipe: run.recipe, revision: run.revision,
+    createdAt: run.createdAt, updatedAt: run.updatedAt, status: facts.status,
+    input: { prompt: run.input.prompt, modelRef: run.input.model_ref,
+      ...(run.input.size !== undefined ? { size: run.input.size } : {}) },
+    source: ref(run.source), output: ref(run.output), comparison: ref(run.comparison), selection: ref(run.selection),
+    task: task ? { id: task.id, acceptance: task.acceptance, outcome: task.outcome,
+      deliveryState: task.deliveryState, attemptCount: task.attempts.length } : null,
+    metrics: facts.metrics ? Object.fromEntries(['ratio', 'diffPixels', 'totalPixels', 'width', 'height']
+      .map(key => [key, facts.metrics[key]])) : null
+  };
+}
+
+export function projectLocalApiRunSummary(run) {
+  return { id: run.id, recipe: run.recipe, createdAt: run.createdAt,
+    modelRef: run.modelRef, source: { artifactId: run.source.artifactId } };
+}