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

package/lib/core-connections.js

@@ -0,0 +1,225 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectExecutionRoot } from './operation-store.js';
+import { checkedBridgeCapabilities, checkedBridgeTools, selectedBridgeTools, DEFAULT_BRIDGE_CAPABILITIES, LEGACY_BRIDGE_TOOLS_V0 } from './core-bridge-selection.js';
+import { CORE_SCOPE_DEFINITIONS } from './core-capability-catalog.js';
+import { checkedPluginSelection, hasPluginSelection } from './plugin-selection.js';
+
+export const CONNECTION_CONTRACT_VERSION = 0;
+export const CONNECTION_SCOPES = Object.freeze(CORE_SCOPE_DEFINITIONS.map(scope => scope.id));
+export const HARNESS_ADAPTERS = Object.freeze([
+  Object.freeze({ adapterId: 'iris.mcp', harnessKinds: ['kimi', 'generic'], transport: 'stdio-to-local-http', contractVersions: [0] }),
+  Object.freeze({ adapterId: 'iris.dsh-service', harnessKinds: ['dsh'], transport: 'local-http', contractVersions: [0] })
+]);
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const TOKEN = /^[A-Za-z0-9_-]{43}$/;
+const hash = value => crypto.createHash('sha256').update(value).digest();
+export function connectionFail(code, message) { throw Object.assign(new Error(message), { code }); }
+function exact(value, fields, optional = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !fields.includes(key) && !optional.includes(key))
+      || !fields.every(field => Object.hasOwn(value, field))) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '连接配置字段无效');
+}
+export function checkedCoreOrigin(value) {
+  const match = typeof value === 'string' && /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/.exec(value);
+  if (!match || Number(match[1]) > 65535) {
+    connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'Core 地址必须是 http://127.0.0.1:端口，不含路径或凭据');
+  }
+  return value;
+}
+function checkedIdentity(value) {
+  const adapter = HARNESS_ADAPTERS.find(item => item.adapterId === value.adapterId);
+  if (!adapter?.harnessKinds.includes(value.harnessKind) || !UUID.test(value.connectionId) || !UUID.test(value.rootId)
+      || typeof value.label !== 'string' || !value.label.trim() || value.label.length > 80
+      || /[\x00-\x1f\x7f]/.test(value.label)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '接入身份或标签无效');
+}
+function checkedScopes(scopes) {
+  if (!Array.isArray(scopes) || !scopes.includes('read') || scopes.length > CONNECTION_SCOPES.length || new Set(scopes).size !== scopes.length
+      || scopes.some(scope => !CONNECTION_SCOPES.includes(scope))) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '连接权限必须包含 read，且仅允许已知的有限范围');
+}
+export { checkedScopes as checkedConnectionScopes };
+export function checkedDeclaredClient(value) {
+  exact(value, ['name', 'version'], ['title']);
+  for (const item of Object.values(value)) {
+    if (typeof item !== 'string' || !item.trim() || item.length > 160 || /[\x00-\x1f\x7f]/.test(item)) {
+      connectionFail('IRIS_CONNECTION_INPUT_INVALID', '客户端声明需要有界名称与版本');
+    }
+  }
+  return structuredClone(value);
+}
+export function projectedMcpClient(value) {
+  if (!value || typeof value.name !== 'string' || typeof value.version !== 'string') return null;
+  const text = item => item.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 160) || 'unknown';
+  return { name: text(value.name), version: text(value.version), ...(typeof value.title === 'string' && value.title.trim() ? { title: text(value.title) } : {}) };
+}
+export function readPrivateConnectionJson(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接文件必须为显式绝对路径');
+  let stat, value;
+  try {
+    stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024 || process.platform !== 'win32' && stat.mode & 0o077) throw new Error('private file required');
+    value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) { connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接文件不可读、格式损坏或权限过宽'); }
+  return value;
+}
+export function checkedClientConnection(value) {
+  exact(value, ['schemaVersion', 'origin', 'rootId', 'connectionId', 'adapterId', 'harnessKind', 'label', 'accessToken'], ['capabilities', 'tools', 'pluginOperations']);
+  if (value.schemaVersion !== 0 || !TOKEN.test(value.accessToken)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接凭据版本或格式不受支持');
+  checkedIdentity(value); checkedCoreOrigin(value.origin);
+  checkedPluginSelection(value.pluginOperations);
+  return { ...structuredClone(value), capabilities: checkedBridgeCapabilities(value.capabilities === undefined ? DEFAULT_BRIDGE_CAPABILITIES : value.capabilities),
+    tools: checkedBridgeTools(value.tools === undefined ? LEGACY_BRIDGE_TOOLS_V0 : value.tools) };
+}
+export function readConnectionGrants(file) {
+  const value = readPrivateConnectionJson(file);
+  exact(value, ['schemaVersion', 'grants']);
+  if (value.schemaVersion !== 0 || !Array.isArray(value.grants) || !value.grants.length || value.grants.length > 32) {
+    connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '需要 1–32 个显式连接授权');
+  }
+  const ids = new Set(), tokens = new Set();
+  for (const grant of value.grants) {
+    exact(grant, ['rootId', 'connectionId', 'adapterId', 'harnessKind', 'label', 'accessToken', 'scopes'], ['capabilities', 'tools', 'pluginOperations']);
+    checkedIdentity(grant); checkedScopes(grant.scopes);
+    checkedPluginSelection(grant.pluginOperations);
+    checkedBridgeCapabilities(grant.capabilities === undefined ? DEFAULT_BRIDGE_CAPABILITIES : grant.capabilities);
+    checkedBridgeTools(grant.tools === undefined ? LEGACY_BRIDGE_TOOLS_V0 : grant.tools);
+    if (!TOKEN.test(grant.accessToken) || ids.has(grant.connectionId) || tokens.has(grant.accessToken)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接身份或凭据重复/无效');
+    ids.add(grant.connectionId); tokens.add(grant.accessToken);
+  }
+  return value.grants.map(grant => ({ ...structuredClone(grant), capabilities: [...(grant.capabilities ?? DEFAULT_BRIDGE_CAPABILITIES)],
+    tools: [...(grant.tools ?? LEGACY_BRIDGE_TOOLS_V0)] }));
+}
+/** Explicit new pairing directory. No harness configuration discovery or modification. */
+export function createConnectionPair({ dataRoot, directory, origin, harnessKind = 'generic', label, scopes = ['read'], capabilities = DEFAULT_BRIDGE_CAPABILITIES, tools, pluginOperations } = {}) {
+  checkedCoreOrigin(origin); checkedScopes(scopes);
+  checkedBridgeCapabilities(capabilities);
+  pluginOperations = checkedPluginSelection(pluginOperations);
+  tools = tools === undefined ? selectedBridgeTools(capabilities, undefined, pluginOperations) : checkedBridgeTools(tools);
+  if (tools.some(name => !selectedBridgeTools(capabilities, undefined, pluginOperations).includes(name))) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '工具不属于所选功能分组');
+  if (typeof dataRoot !== 'string' || !path.isAbsolute(dataRoot)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '需要明确的 v1 数据根绝对路径');
+  const adapterId = harnessKind === 'dsh' ? 'iris.dsh-service' : 'iris.mcp';
+  const root = fs.realpathSync.native(dataRoot), marker = inspectExecutionRoot(root);
+  const client = { schemaVersion: 0, origin, rootId: marker.rootId, connectionId: crypto.randomUUID(), adapterId, harnessKind, label,
+    accessToken: crypto.randomBytes(32).toString('base64url'), capabilities: [...capabilities], tools: [...tools], ...(pluginOperations.length ? { pluginOperations } : {}) };
+  checkedClientConnection(client);
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '输出目录须为新的绝对路径');
+  const relative = path.relative(root, path.join(fs.realpathSync.native(path.dirname(directory)), path.basename(directory)));
+  if (!relative || !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '连接凭据须存放在数据根之外');
+  fs.mkdirSync(directory, { mode: 0o700 });
+  const serverFile = path.join(directory, 'server-grants.json'), clientFile = path.join(directory, 'client.json');
+  const { schemaVersion: _version, origin: _origin, ...grant } = client;
+  fs.writeFileSync(serverFile, JSON.stringify({ schemaVersion: 0, grants: [{ ...grant, scopes }] }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  fs.writeFileSync(clientFile, JSON.stringify(client, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  return { contractVersion: 0, connectionId: client.connectionId, adapterId, harnessKind, scopes, capabilities, tools, serverFile, clientFile };
+}
+
+/** Authenticated, per-connection and per-runtime facts. No filesystem or Provider access. */
+export function createConnectionRegistry(grants, availableScopes, { onClientInfo = () => {}, availableCapabilities, availableTools } = {}) {
+  const configured = new Map(grants.map(grant => {
+    const { accessToken, ...publicGrant } = grant;
+    return [grant.connectionId, { ...structuredClone(publicGrant), capabilities: [...(grant.capabilities ?? DEFAULT_BRIDGE_CAPABILITIES)],
+      tools: [...(grant.tools ?? LEGACY_BRIDGE_TOOLS_V0)], tokenDigest: hash(accessToken), instances: new Map() }];
+  }));
+  function identify(connectionId, token) {
+    const grant = configured.get(connectionId);
+    if (!grant || !TOKEN.test(token) || !crypto.timingSafeEqual(hash(token), grant.tokenDigest)) connectionFail('IRIS_CONNECTION_AUTH_REQUIRED', '连接身份或凭据无效');
+    return grant.connectionId;
+  }
+  function handshake(connectionId, value) {
+    exact(value, ['contractVersion', 'adapterId', 'harnessKind', 'runtimeInstanceId', 'harnessVersion', 'requestedScopes'], ['requestedCapabilities', 'requestedTools', 'requestedPluginOperations']);
+    const grant = configured.get(connectionId);
+    if (value.contractVersion !== 0) connectionFail('IRIS_CONNECTION_VERSION_UNSUPPORTED', '连接契约版本不受支持');
+    if (value.adapterId !== grant.adapterId || value.harnessKind !== grant.harnessKind || !UUID.test(value.runtimeInstanceId)
+        || typeof value.harnessVersion !== 'string' || value.harnessVersion.length > 80 || /[\x00-\x1f\x7f]/.test(value.harnessVersion)) {
+      connectionFail('IRIS_CONNECTION_INPUT_INVALID', '握手身份不符合本地授权');
+    }
+    checkedScopes(value.requestedScopes);
+    const capabilities = checkedBridgeCapabilities(value.requestedCapabilities === undefined ? grant.capabilities : value.requestedCapabilities);
+    const tools = checkedBridgeTools(value.requestedTools === undefined ? grant.tools : value.requestedTools);
+    const pluginOperations = checkedPluginSelection(value.requestedPluginOperations === undefined ? grant.pluginOperations : value.requestedPluginOperations);
+    if (pluginOperations.some(pin => !hasPluginSelection(grant.pluginOperations || [], pin))) connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '插件业务或版本不在明确授权中');
+    if (value.requestedScopes.some(scope => !grant.scopes.includes(scope) || !availableScopes.includes(scope))) {
+      connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '请求的能力未获授权或服务未开启');
+    }
+    if (capabilities.some(id => !grant.capabilities.includes(id) || availableCapabilities && !availableCapabilities.includes(id)) || tools.some(name => !grant.tools.includes(name))) {
+      connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '请求的功能或工具未获本地授权');
+    }
+    if (!grant.instances.has(value.runtimeInstanceId) && grant.instances.size >= 8) {
+      const retired = [...grant.instances.values()].find(instance => instance.state === 'disconnected');
+      if (retired) grant.instances.delete(retired.runtimeInstanceId);
+      else connectionFail('IRIS_CONNECTION_BUSY', '该连接实例数量已达上限，请由 owner 明确断开旧实例');
+    }
+    const now = new Date().toISOString(), instance = { runtimeInstanceId: value.runtimeInstanceId, harnessVersion: value.harnessVersion,
+      connectedAt: now, lastSeenAt: now, state: 'connected', scopes: [...value.requestedScopes], capabilities,
+      tools: selectedBridgeTools(capabilities, tools, pluginOperations).filter(name => availableTools === undefined || availableTools.includes(name)),
+      ...(pluginOperations.length ? { pluginOperations } : {}),
+      verification: 'handshake', liveness: 'not_probed' };
+    grant.instances.set(value.runtimeInstanceId, instance);
+    return { contractVersion: 0, rootId: grant.rootId, connectionId, adapterId: grant.adapterId, harnessKind: grant.harnessKind,
+      instance: structuredClone(instance), remoteHostPorts: [], connectionFeatures: ['client-info'] };
+  }
+  function authorize(connectionId, runtimeInstanceId, scope, tool) {
+    const grant = configured.get(connectionId), instance = grant?.instances.get(runtimeInstanceId);
+    if (!instance || instance.state !== 'connected') connectionFail('IRIS_CONNECTION_HANDSHAKE_REQUIRED', '请先完成本次服务的连接握手');
+    if (!instance.scopes.includes(scope)) connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '此连接未获该操作权限');
+    if (tool && !instance.tools.includes(tool)) connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '此功能或工具未被用户选择');
+    instance.lastSeenAt = new Date().toISOString();
+    return [...instance.scopes];
+  }
+  function disconnect(connectionId, runtimeInstanceId) {
+    const instance = configured.get(connectionId)?.instances.get(runtimeInstanceId);
+    if (!instance) connectionFail('IRIS_CONNECTION_HANDSHAKE_REQUIRED', '没有此连接实例');
+    instance.state = 'disconnected'; instance.lastSeenAt = new Date().toISOString();
+    return { contractVersion: 0, disconnected: true };
+  }
+  function list(connectionId) {
+    return { contractVersion: 0, adapters: structuredClone(HARNESS_ADAPTERS), connections: [...configured.values()]
+      .filter(grant => connectionId === undefined || grant.connectionId === connectionId)
+      .map(({ tokenDigest: _secret, instances, ...grant }) => ({ ...structuredClone(grant), configured: true,
+        harnessInstalled: 'unknown', instances: [...instances.values()].map(instance => structuredClone(instance)) })) };
+  }
+  function dispose() { for (const grant of configured.values()) grant.tokenDigest.fill(0); configured.clear(); }
+  function selection(connectionId, runtimeInstanceId) {
+    const instance = configured.get(connectionId).instances.get(runtimeInstanceId);
+    return { capabilities: [...instance.capabilities], tools: [...instance.tools], ...(instance.pluginOperations?.length ? { pluginOperations: structuredClone(instance.pluginOperations) } : {}) };
+  }
+  function clientInfo(connectionId, runtimeInstanceId, value) {
+    exact(value, ['clientInfo', 'transport']);
+    const info = checkedDeclaredClient(value.clientInfo);
+    if (!['stdio', 'http'].includes(value.transport)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'MCP 传输声明无效');
+    const instance = configured.get(connectionId)?.instances.get(runtimeInstanceId);
+    if (!instance || instance.state !== 'connected') connectionFail('IRIS_CONNECTION_HANDSHAKE_REQUIRED', '请先连接当前实例');
+    const contact = { clientInfo: info, transport: value.transport, source: 'client-declared', at: new Date().toISOString() };
+    onClientInfo(connectionId, contact);
+    instance.declaredClient = contact; instance.lastSeenAt = contact.at;
+    return { contractVersion: 0, recorded: true };
+  }
+  function setGrant(grant) {
+    const old = configured.get(grant.connectionId), { accessToken, ...publicGrant } = grant;
+    const same = old && crypto.timingSafeEqual(old.tokenDigest, hash(accessToken))
+      && ['adapterId', 'harnessKind', 'scopes', 'capabilities', 'tools', 'pluginOperations'].every(key => JSON.stringify(old[key]) === JSON.stringify(publicGrant[key]));
+    if (old) old.tokenDigest.fill(0);
+    configured.set(grant.connectionId, { ...structuredClone(publicGrant), tokenDigest: hash(accessToken), instances: same ? old.instances : new Map() });
+    return { authorizationChanged: !same };
+  }
+  function revoke(connectionId) {
+    const grant = configured.get(connectionId);
+    if (grant) { grant.tokenDigest.fill(0); configured.delete(connectionId); }
+  }
+  function identifyMcp(token) {
+    if (!TOKEN.test(token)) connectionFail('IRIS_CONNECTION_AUTH_REQUIRED', '需要明确的 MCP 连接凭据');
+    const tokenDigest = hash(token);
+    const grant = [...configured.values()].find(item => crypto.timingSafeEqual(tokenDigest, item.tokenDigest));
+    if (!grant) connectionFail('IRIS_CONNECTION_AUTH_REQUIRED', 'MCP 连接凭据无效');
+    if (grant.adapterId !== 'iris.mcp') connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '此凭据没有授权 MCP 接入');
+    const { tokenDigest: _secret, instances: _instances, ...publicGrant } = grant;
+    return structuredClone(publicGrant);
+  }
+  function authorizePlugin(connectionId, dependency) {
+    const grant = configured.get(connectionId);
+    if (!grant?.scopes.includes('execute') || !grant.tools.includes('iris_core_plugin_call') || !hasPluginSelection(grant.pluginOperations || [], dependency)) {
+      connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '原连接的插件业务执行授权已缩减或撤销');
+    }
+  }
+  return Object.freeze({ identify, identifyMcp, handshake, authorize, authorizePlugin, selection, disconnect, list, clientInfo, setGrant, revoke, dispose });
+}

package/lib/core-delivery-cache.js

@@ -5,6 +5,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { atomicWritePrivate, ensurePrivateDir } from './private-storage.js';
+import { assertProviderMediaSize } from './provider-response.js';
 
 const TASK_ID = /^task_[a-f0-9]{24}$/;
 const ARTIFACT_ID = /^artifact_[a-f0-9]{24}$/;
@@ -42,9 +43,10 @@ function regular(file) {
   return stat;
 }
 
-function fingerprint(file) {
+function fingerprint(file, capability) {
   const stat = regular(file);
   if (!stat.size) invalid();
+  assertProviderMediaSize(stat.size, capability);
   const hash = crypto.createHash('sha256');
   const chunk = Buffer.alloc(1024 * 1024);
   const fd = fs.openSync(file, 'r');
@@ -75,6 +77,8 @@ export function createDeliveryCache(dataRoot, task, artifacts) {
     if (remote.kind === 'remote-url') {
       item.source = { kind: 'remote-url', url: remote.url, ...(remote.mediaType ? { mediaType: remote.mediaType } : {}) };
     } else if (remote.kind === 'inline-base64') {
+      const padding = remote.data.endsWith('==') ? 2 : remote.data.endsWith('=') ? 1 : 0;
+      assertProviderMediaSize(remote.data.length / 4 * 3 - padding, task.capability);
       const bytes = Buffer.from(remote.data, 'base64');
       if (!bytes.length || bytes.toString('base64') !== remote.data) invalid();
       const file = 'payload-' + crypto.randomBytes(12).toString('hex') + '.bin';
@@ -130,7 +134,7 @@ export function newDeliveryPayloadPath(dataRoot, cache) {
 export function recordDeliveryPayload(dataRoot, cache, index, file, mediaType) {
   const root = directory(dataRoot, cache.taskId);
   if (path.dirname(file) !== root || !PAYLOAD_FILE.test(path.basename(file))) invalid();
-  cache.items[index].payload = { file: path.basename(file), ...fingerprint(file), mediaType };
+  cache.items[index].payload = { file: path.basename(file), ...fingerprint(file, cache.capability), mediaType };
   delete cache.items[index].source;
   save(dataRoot, cache);
 }
@@ -139,7 +143,8 @@ export function readDeliveryPayload(dataRoot, cache, index) {
   const payload = cache.items[index].payload;
   const file = path.join(directory(dataRoot, cache.taskId), payload.file);
   let actual;
-  try { actual = fingerprint(file); } catch (_) { invalid(); }
+  try { actual = fingerprint(file, cache.capability); }
+  catch (error) { if (error.code === 'IRIS_PROVIDER_RESPONSE_TOO_LARGE') throw error; invalid(); }
   if (actual.size !== payload.size || actual.sha256 !== payload.sha256) invalid();
   return file;
 }

package/lib/core-maintenance.js

@@ -5,8 +5,9 @@ import { inspectCoreArtifact, refreshCoreArtifactInventory } from './core-artifa
 import { assertFlowTaskMatches, inspectCoreTask, listCoreTasks } from './core-tasks.js';
 import { atomicWritePrivate } from './private-storage.js';
 import { readDeliveryCache } from './core-delivery-cache.js';
-import { flowReferences } from './flow-store.js';
+import { flowReferences, flowStep } from './flow-store.js';
 import { creationReferences } from './creation-request-store.js';
+import { operationReferences } from './operation-store.js';
 
 const TASK = /^task_[a-f0-9]{24}$/;
 const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
@@ -55,7 +56,7 @@ function inventory(root) {
     .map(name => inspectCoreArtifact(root, name.slice(0, -5)));
   const flows = flowReferences(root);
   for (const reference of flows) {
-    if (reference.run.edit.claimed && !tasks.some(task => task.id === reference.run.edit.taskId)) {
+    if (flowStep(reference.run).claimed && !tasks.some(task => task.id === flowStep(reference.run).taskId)) {
       fail('IRIS_FLOW_TASK_CONFLICT', '流程已建立的 Task 丢失，停止管理');
     }
   }
@@ -64,7 +65,7 @@ function inventory(root) {
     if (!reference) fail('IRIS_FLOW_TASK_CONFLICT', '流程 Task 的 Run 记录丢失，停止管理');
     assertFlowTaskMatches(task, reference.run);
   }
-  return { tasks, artifacts, flows, creations: creationReferences(root) };
+  return { tasks, artifacts, flows, creations: creationReferences(root), operations: operationReferences(root) };
 }
 
 function ids(value, pattern, label) {
@@ -78,6 +79,10 @@ export function planCoreDeletion(root, input) {
   if (!taskIds.length && !artifactIds.length) fail('IRIS_COMMAND_INPUT_INVALID', '请明确指定 Task 或 Artifact ID');
   const existing = inventory(root), selectedTasks = new Set(taskIds), selectedArtifacts = new Set(artifactIds);
   const blockers = [], files = [];
+  for (const reference of existing.operations) {
+    for (const id of reference.taskIds) if (selectedTasks.has(id)) blockers.push({ id, referencedBy: reference.operationId, reason: 'operation_task_reference' });
+    for (const id of reference.artifactIds) if (selectedArtifacts.has(id)) blockers.push({ id, referencedBy: reference.operationId, reason: 'operation_artifact_reference' });
+  }
   for (const reference of existing.creations) {
     for (const id of reference.taskIds) if (selectedTasks.has(id)) blockers.push({ id, referencedBy: reference.requestId, reason: 'creation_task_reference' });
     for (const id of reference.artifactIds) if (selectedArtifacts.has(id)) blockers.push({ id, referencedBy: reference.requestId, reason: 'creation_artifact_reference' });
@@ -136,6 +141,7 @@ export function planCoreCleanup(root, { older_than_ms = 3600000 } = {}) {
   if (!Number.isSafeInteger(older_than_ms) || older_than_ms < 60000) fail('IRIS_COMMAND_INPUT_INVALID', 'older_than_ms 至少为 60000');
   const existing = inventory(root);
   const referenced = new Set(existing.artifacts.map(artifact => artifact.id));
+  for (const reference of existing.operations) for (const id of reference.artifactIds) referenced.add(id);
   for (const reference of existing.creations) for (const id of reference.artifactIds) referenced.add(id);
   for (const reference of existing.flows) for (const id of reference.artifactIds) referenced.add(id);
   for (const artifact of existing.artifacts) for (const edge of artifact.relations) referenced.add(edge.artifactId);

package/lib/core-runtime.js

@@ -14,6 +14,7 @@ import {
 } from './core-contract.js';
 import { ensurePrivateDir } from './private-storage.js';
 import { listCreationRequests } from './creation-request-store.js';
+import { readAllOperations } from './operation-store.js';
 import { WRITER_LEASE_DIR, WRITER_INTENT_FILE, publishLeaseRecord, readWriterLease,
   removeWriterIntent, retireLeaseDirectory, writerOwnerStatus } from './core-writer-lease.js';
 
@@ -164,7 +165,7 @@ export function createCoreRuntime(input) {
     const candidateRoot = physicalDataRoot(options);
     const candidateLease = options.mode === 'writer' ? acquireWriterLease(candidateRoot, instanceId) : null;
     if (candidateLease) {
-      try { listCreationRequests(candidateRoot); }
+      try { listCreationRequests(candidateRoot); readAllOperations(candidateRoot); }
       catch (error) {
         try { releaseWriterLease(candidateLease); }
         catch (cleanupError) {

package/lib/core-service-client.js

@@ -0,0 +1,174 @@
+import crypto from 'node:crypto';
+import { checkedClientConnection, readPrivateConnectionJson, connectionFail } from './core-connections.js';
+import { MAX_IMPORT_IMAGE_BYTES } from './image-import.js';
+import { MAX_VIDEO_BYTES, VIDEO_TYPES } from './video-flow-input.js';
+import { annotateCoreConnectionError } from './core-connection-diagnostics.js';
+import { checkedPluginSelection, hasPluginSelection } from './plugin-selection.js';
+
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const RUN = /^run_[a-f0-9]{24}$/, OP = /^op_[a-f0-9]{64}$/, ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+const input = () => connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'Core 服务工具输入无效');
+function reference(value, pattern) { if (typeof value !== 'string' || !pattern.test(value)) input(); return value; }
+
+/** A bounded client of one explicitly authorized Core. It never owns a Core writer or falls back. */
+export function createCoreServiceClient({ connectionFile, connection, requestedScopes = ['read'], requestedCapabilities, requestedTools, requestedPluginOperations,
+  harnessVersion = 'unknown', fetch: fetchImpl = globalThis.fetch } = {}) {
+  if (connectionFile !== undefined && connection !== undefined) throw new TypeError('连接配置只能明确提供一种来源');
+  const runtimeInstanceId = crypto.randomUUID(), lifetime = new AbortController();
+  let state = 'new', config, negotiated, connectionPromise, metadataPromise, metadataKey, metadataAt = 0, disposal;
+  async function request(route, { method = 'GET', value, bytes, key, mediaType, binary = false, signal, handshake = false, disconnect = false } = {}) {
+    if (state !== 'open' && !(handshake && state === 'connecting') && !(disconnect && state === 'closing')) connectionFail('IRIS_CORE_SERVICE_DISCONNECTED', 'Core 服务尚未连接，请显式连接');
+    const headers = { Authorization: 'Bearer ' + config.accessToken, 'Iris-Connection-Id': config.connectionId, 'Iris-Runtime-Id': runtimeInstanceId };
+    if (key !== undefined) headers['Idempotency-Key'] = reference(key, UUID);
+    if (value !== undefined || bytes !== undefined) headers['Content-Type'] = mediaType || 'application/json';
+    const combined = AbortSignal.any([...(disconnect ? [] : [lifetime.signal]), AbortSignal.timeout(disconnect ? 2000 : 15000), ...(signal ? [signal] : [])]);
+    let response;
+    try {
+      response = await fetchImpl(config.origin + route, { method, headers, redirect: 'error', signal: combined,
+        ...(value !== undefined ? { body: JSON.stringify(value) } : bytes !== undefined ? { body: bytes } : {}) });
+    } catch (error) {
+      if (signal?.aborted || !disconnect && lifetime.signal.aborted) throw Object.assign(new Error('Core 请求等待已停止；已接收操作需按原 Key 查询'), { name: 'AbortError', code: 'IRIS_CORE_SERVICE_ABORTED' });
+      throw annotateCoreConnectionError(Object.assign(new Error('Core 服务无法连接，请检查服务状态'), {
+        code: combined.reason?.name === 'TimeoutError' ? 'IRIS_CORE_SERVICE_TIMEOUT' : 'IRIS_CORE_SERVICE_UNAVAILABLE' }), 'transport');
+    }
+    const limit = binary && binary !== 'text' && response.ok ? binary === 'video' ? MAX_VIDEO_BYTES : 64 * 1024 * 1024 : 1024 * 1024;
+    if (Number(response.headers.get('content-length')) > limit) { await response.body?.cancel(); connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 响应超过有界大小'); }
+    const chunks = []; let size = 0;
+    try {
+      if (response.body) for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > limit) connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 响应超过有界大小');
+        chunks.push(chunk);
+      }
+    } catch (error) {
+      if (error.code === 'IRIS_CORE_SERVICE_RESPONSE_INVALID') throw error;
+      connectionFail('IRIS_CORE_SERVICE_UNAVAILABLE', 'Core 响应中断；请读取原 Operation，不要自动再次提交');
+    }
+    const result = Buffer.concat(chunks, size);
+    if (binary && response.ok) {
+      const mediaType = response.headers.get('content-type');
+      const allowed = binary === 'video' ? Object.keys(VIDEO_TYPES) : binary === 'audio' ? ['audio/wav', 'audio/mpeg', 'audio/ogg', 'audio/flac'] : binary === 'text' ? ['text/plain'] : ['image/png', 'image/jpeg', 'image/webp'];
+      if (!allowed.includes(mediaType)) connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core返回的作品类型与所选入口不一致');
+      return { bytes: result, mediaType };
+    }
+    let body;
+    try { body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(result)); }
+    catch (_) { connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 返回无效 JSON'); }
+    if (!response.ok) {
+      const code = /^IRIS_[A-Z_]+$/.test(body?.error?.code) ? body.error.code : 'IRIS_CORE_SERVICE_REJECTED';
+      throw annotateCoreConnectionError(Object.assign(new Error('Core 服务拒绝本次请求；请检查授权、原操作及服务状态'), {
+        code, status: response.status, ...(UUID.test(body?.error?.requestId) ? { requestId: body.error.requestId } : {}) }), handshake ? 'handshake' : disconnect ? 'disconnect' : 'tool');
+    }
+    if (body?.contractVersion !== 0) connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 响应契约不受支持');
+    return body;
+  }
+  function connect() {
+    if (['closing', 'closed'].includes(state)) return Promise.reject(Object.assign(new Error('Core 连接已关闭'), { code: 'IRIS_CORE_SERVICE_DISCONNECTED' }));
+    if (connectionPromise) return connectionPromise;
+    connectionPromise = (async () => {
+      let stage = 'configuration';
+      try {
+        config = checkedClientConnection(connection ?? readPrivateConnectionJson(connectionFile));
+        state = 'connecting'; stage = 'handshake';
+        const pluginChoice = requestedPluginOperations === undefined ? config.pluginOperations : requestedPluginOperations;
+        const result = await request('/api/v0/connections/' + config.connectionId + '/handshake', { method: 'POST', handshake: true,
+          value: { contractVersion: 0, adapterId: config.adapterId, harnessKind: config.harnessKind, runtimeInstanceId,
+            harnessVersion, requestedScopes, requestedCapabilities: requestedCapabilities ?? config.capabilities,
+            requestedTools: requestedTools ?? config.tools,
+            ...(pluginChoice === undefined ? {} : { requestedPluginOperations: checkedPluginSelection(pluginChoice) }) } });
+        if (state !== 'connecting') connectionFail('IRIS_CORE_SERVICE_ABORTED', '连接启动等待已停止');
+        if (result.rootId !== config.rootId || result.connectionId !== config.connectionId || result.instance?.runtimeInstanceId !== runtimeInstanceId
+            || !Array.isArray(result.instance.scopes) || result.instance.scopes.some(scope => !requestedScopes.includes(scope))
+            || !Array.isArray(result.instance.capabilities) || result.instance.capabilities.some(id => !(requestedCapabilities ?? config.capabilities).includes(id))
+            || !Array.isArray(result.instance.tools) || result.instance.tools.some(name => !(requestedTools ?? config.tools).includes(name))) {
+          connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 数据空间或协商身份不一致');
+        }
+        if (checkedPluginSelection(result.instance.pluginOperations).some(pin => !hasPluginSelection(pluginChoice ?? [], pin))) {
+          connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 返回了未请求的插件业务依赖');
+        }
+        negotiated = result; metadataKey = null; metadataAt = 0; state = 'open'; return structuredClone(result);
+      } catch (error) { if (!['closing', 'closed'].includes(state)) state = 'disconnected'; throw annotateCoreConnectionError(error, stage); }
+    })();
+    void connectionPromise.then(() => { connectionPromise = null; }, () => { connectionPromise = null; });
+    return connectionPromise;
+  }
+  function snapshot() {
+    return { contractVersion: 0, state, ...(config ? { connectionId: config.connectionId, adapterId: config.adapterId,
+      harnessKind: config.harnessKind, label: config.label, runtimeInstanceId, scopes: negotiated?.instance.scopes || [],
+      capabilities: negotiated?.instance.capabilities || [], tools: negotiated?.instance.tools || [],
+      ...(negotiated?.instance.pluginOperations?.length ? { pluginOperations: structuredClone(negotiated.instance.pluginOperations) } : {}) } : {}) };
+  }
+  async function reportClientInfo(clientInfo, transport) {
+    if (!clientInfo || !negotiated?.connectionFeatures?.includes('client-info')) return;
+    const key = JSON.stringify({ clientInfo, transport });
+    if (key === metadataKey && Date.now() - metadataAt < 60000) return metadataPromise;
+    metadataKey = key; metadataAt = Date.now();
+    const attempt = request('/api/v0/connections/' + config.connectionId + '/client-info', { method: 'POST', value: { clientInfo, transport } });
+    metadataPromise = attempt;
+    void attempt.catch(() => { if (metadataPromise === attempt) { metadataKey = null; metadataAt = 0; } });
+    return metadataPromise;
+  }
+  function dispose() {
+    if (disposal) return disposal;
+    const wasOpen = state === 'open', starting = connectionPromise;
+    state = 'closing'; lifetime.abort();
+    disposal = (async () => {
+      let remoteDisconnect = wasOpen ? 'unconfirmed' : 'not_connected';
+      try {
+        if (wasOpen) {
+          await request('/api/v0/connections/' + config.connectionId + '/disconnect', { method: 'POST', value: {}, disconnect: true });
+          remoteDisconnect = 'confirmed';
+        }
+      } catch (error) {
+        if (!['IRIS_CORE_SERVICE_UNAVAILABLE', 'IRIS_CORE_SERVICE_TIMEOUT', 'IRIS_CORE_SERVICE_ABORTED', 'IRIS_CONNECTION_HANDSHAKE_REQUIRED',
+          'IRIS_CONNECTION_AUTH_REQUIRED', 'IRIS_API_AUTH_REQUIRED', 'IRIS_API_UNAVAILABLE'].includes(error.code)) throw error;
+      } finally {
+        await Promise.allSettled([starting, metadataPromise].filter(Boolean));
+        state = 'closed'; negotiated = null; config = null;
+      }
+      return { state, remoteDisconnect };
+    })();
+    return disposal;
+  }
+  function pageQuery(value = {}) {
+    if (!value || typeof value !== 'object' || Object.keys(value).some(key => !['limit', 'cursor'].includes(key))
+        || value.limit !== undefined && (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > 30)
+        || value.cursor !== undefined && typeof value.cursor !== 'string') input();
+    return new URLSearchParams(Object.fromEntries(Object.entries(value).map(([key, value]) => [key, String(value)]))).toString();
+  }
+  return Object.freeze({ connect, dispose, snapshot, reportClientInfo,
+    pluginCatalog: (page, options) => request('/api/v0/plugin-operations/catalog?' + new URLSearchParams(page), options),
+    callPlugin({ key, ...value }, options) { return request('/api/v0/plugin-operations', { ...options, method: 'POST', value, key }); },
+    models: options => request('/api/v0/models', options),
+    audioModels: options => request('/api/v0/audio-models', options),
+    videoModels: options => request('/api/v0/video-models', options),
+    connections: options => request('/api/v0/connections', options),
+    runs: (page, options) => request('/api/v0/runs?' + pageQuery(page), options),
+    run: (id, options) => request('/api/v0/runs/' + reference(id, RUN), options),
+    image: (id, options) => request('/api/v0/artifacts/' + reference(id, ARTIFACT) + '/content', { ...options, binary: true }),
+    audio: (id, options) => request('/api/v0/artifacts/' + reference(id, ARTIFACT) + '/audio', { ...options, binary: 'audio' }),
+    video: (id, options) => request('/api/v0/artifacts/' + reference(id, ARTIFACT) + '/video', { ...options, binary: 'video' }),
+    transcript: (id, options) => request('/api/v0/artifacts/' + reference(id, ARTIFACT) + '/text', { ...options, binary: 'text' }),
+    createImage({ key, bytes, mediaType }, options) {
+      if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > MAX_IMPORT_IMAGE_BYTES || !['image/png', 'image/jpeg', 'image/webp'].includes(mediaType)) input();
+      return request('/api/v0/images', { ...options, method: 'POST', bytes, key, mediaType });
+    },
+    createRun({ key, value }, options) { return request('/api/v0/runs', { ...options, method: 'POST', value, key }); },
+    createGeneration({ key, value }, options) { return request('/api/v0/generations', { ...options, method: 'POST', value, key }); },
+    createVideo({ key, value }, options) { return request('/api/v0/videos', { ...options, method: 'POST', value, key }); },
+    createAudio({ key, bytes, mediaType }, options) {
+      if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 20 * 1024 * 1024 || !['audio/wav', 'audio/mpeg', 'audio/ogg', 'audio/flac'].includes(mediaType)) input();
+      return request('/api/v0/audio', { ...options, method: 'POST', bytes, key, mediaType });
+    },
+    createSpeech({ key, value }, options) { return request('/api/v0/speeches', { ...options, method: 'POST', value, key }); },
+    createTranscription({ key, value }, options) { return request('/api/v0/transcriptions', { ...options, method: 'POST', value, key }); },
+    continueRun({ key, runId, expectedRevision }, options) {
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1) input();
+      return request('/api/v0/runs/' + reference(runId, RUN) + '/continue', { ...options, method: 'POST', value: { expectedRevision }, key });
+    },
+    operation: (id, options) => request('/api/v0/operations/' + reference(id, OP), options),
+    lookup: (key, options) => request('/api/v0/operations?key=' + reference(key, UUID), options),
+    operations: (runId, page, options) => request('/api/v0/runs/' + reference(runId, RUN) + '/operations?' + pageQuery(page), options),
+    stop: (id, options) => request('/api/v0/operations/' + reference(id, OP) + '/cancel', { ...options, method: 'POST', value: {} })
+  });
+}