@xmanrui/dsh-im 4.9.1 → 4.11.0

package/src/channels/shared/harness-client.mjs

@@ -24,6 +24,8 @@ import { watchHarnessMux } from './harness-mux.mjs';
 const interactionRegistries = new Map();
 const hostInteractionRegistries = new WeakMap();
 const MAX_ERROR_CLASSIFICATION_BYTES = 64;
+const IM_INPUT_ORIGIN_TTL_MS = 30 * 60 * 1000;
+const MAX_IM_INPUT_ORIGINS = 4096;
 
 async function smallResponseText(response) {
   const stream = response?.body;
@@ -91,6 +93,7 @@ function interactionRegistry(scope) {
       ownerships: new Map(),
       claims: new Map(),
       controls: new WeakMap(),
+      imInputOrigins: new Map(),
       nextOrder: 0,
     };
     registries.set(scope, registry);
@@ -98,6 +101,34 @@ function interactionRegistry(scope) {
   return registry;
 }
 
+function pruneImInputOrigins(origins, now = Date.now()) {
+  for (const [rpcId, expiresAt] of origins) {
+    if (expiresAt > now) continue;
+    origins.delete(rpcId);
+  }
+  while (origins.size > MAX_IM_INPUT_ORIGINS) {
+    origins.delete(origins.keys().next().value);
+  }
+}
+
+function registerImInputOrigin(registry, rpcId) {
+  const origins = registry.imInputOrigins;
+  pruneImInputOrigins(origins);
+  origins.delete(rpcId);
+  origins.set(rpcId, Date.now() + IM_INPUT_ORIGIN_TTL_MS);
+  pruneImInputOrigins(origins);
+  return () => origins.delete(rpcId);
+}
+
+/** Consume a dsh-im prompt id while handling its durable user/message event. */
+export function consumeDshImInputOrigin(scope, rpcId) {
+  if (!scope || !['object', 'function', 'string'].includes(typeof scope)
+    || typeof rpcId !== 'string' || !rpcId) return false;
+  const origins = interactionRegistry(scope).imInputOrigins;
+  pruneImInputOrigins(origins);
+  return origins.delete(rpcId);
+}
+
 // A Host RPC may not accept cancellation itself. Bound the caller's wait
 // without retrying an operation that the Host may already have accepted.
 function callWithSignal(call, signal) {
@@ -311,14 +342,59 @@ function sleep(ms, signal) {
   });
 }
 
-function assistantMessageText(event) {
-  return (event?.data?.message?.content ?? [])
-    .filter((part) => part.type === 'text' && typeof part.text === 'string')
+/** Join only visible text blocks from one Harness message payload. */
+export function textFromHarnessContent(content) {
+  return (Array.isArray(content) ? content : [])
+    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
     .map((part) => part.text)
     .join('\n')
     .trim();
 }
 
+function assistantMessageText(event) {
+  return textFromHarnessContent(event?.data?.message?.content);
+}
+
+/** Aggregate assistant text in stable step/index order for one Harness Turn. */
+export class AssistantTextAccumulator {
+  #steps = new Map();
+  #legacyText = '';
+
+  appendDelta(step, index, text) {
+    if (typeof text !== 'string' || !text) return;
+    const stepNumber = Number.isSafeInteger(step) ? step : 0;
+    const partIndex = Number.isSafeInteger(index) ? index : 0;
+    this.#legacyText = '';
+    const parts = this.#steps.get(stepNumber) ?? new Map();
+    parts.set(partIndex, (parts.get(partIndex) ?? '') + text);
+    this.#steps.set(stepNumber, parts);
+  }
+
+  setCanonical(step, text) {
+    if (typeof text !== 'string' || !text.trim()) return;
+    if (!Number.isSafeInteger(step)) {
+      this.#steps.clear();
+      this.#legacyText = text.trim();
+      return;
+    }
+    this.#legacyText = '';
+    this.#steps.set(step, new Map([[0, text.trim()]]));
+  }
+
+  get text() {
+    if (this.#steps.size === 0) return this.#legacyText;
+    return [...this.#steps.entries()]
+      .sort(([left], [right]) => left - right)
+      .map(([, parts]) => [...parts.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([, text]) => text)
+        .join('\n')
+        .trim())
+      .filter(Boolean)
+      .join('\n\n');
+  }
+}
+
 function nonEmptyText(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
@@ -418,7 +494,7 @@ export class HarnessReplyTracker {
   #lastSeq;
   #openTurn = null;
   #targetTurn = null;
-  #stepText = new Map();
+  #assistantText = new AssistantTextAccumulator();
   #latestText = '';
   #finished = false;
   #reason = null;
@@ -455,6 +531,12 @@ export class HarnessReplyTracker {
     return this.#targetTurn;
   }
 
+  #commitText(text, pushUpdate) {
+    if (!text || text === this.#latestText) return;
+    this.#latestText = text;
+    pushUpdate({ type: 'text', text });
+  }
+
   consumeAll(entries) {
     const updates = [];
     // 同一批轮询内的 text 帧只保留最新累积，其余事件逐帧透出，
@@ -499,28 +581,16 @@ export class HarnessReplyTracker {
       if (event.type === 'assistant/chunk' && event.data?.chunk?.type === 'text-delta') {
         const step = event.data?.step ?? 0;
         const index = event.data.chunk.index ?? 0;
-        const key = `${step}:${index}`;
-        this.#stepText.set(key, (this.#stepText.get(key) ?? '') + event.data.chunk.text);
-        const prefix = `${step}:`;
-        const text = [...this.#stepText.entries()]
-          .filter(([partKey]) => partKey.startsWith(prefix))
-          .sort(([left], [right]) => Number(left.split(':')[1]) - Number(right.split(':')[1]))
-          .map(([, part]) => part)
-          .join('\n')
-          .trim();
-        if (text && text !== this.#latestText) {
-          this.#latestText = text;
-          pushUpdate({ type: 'text', text });
-        }
+        this.#assistantText.appendDelta(step, index, event.data.chunk.text);
+        this.#commitText(this.#assistantText.text, pushUpdate);
         continue;
       }
 
       if (event.type === 'assistant/message') {
         const text = assistantMessageText(event);
-        if (text && text !== this.#latestText) {
-          this.#latestText = text;
-          pushUpdate({ type: 'text', text });
-        }
+        const step = Number.isSafeInteger(event.data?.step) ? event.data.step : null;
+        this.#assistantText.setCanonical(step, text);
+        this.#commitText(this.#assistantText.text, pushUpdate);
         continue;
       }
 
@@ -1188,31 +1258,40 @@ export class HarnessClient {
     const ownership = await this.#refreshControlOwnership(sessionId, control, options);
     if (!ownership || ownership.stopRequested) return false;
     if (this.#activeControlOwnership(sessionId, control) !== ownership) return false;
-    if (this.#controlExecutor) {
-      const accepted = this.#controlExecutor({
-        sessionId,
-        expectedTurn: ownership.turn,
-        promptRpcId: ownership.promptRpcId,
-        action: 'steer',
-        text,
-      });
-      if (accepted && typeof accepted.then === 'function') {
-        throw new TypeError('controlExecutor must return synchronously');
-      }
-      if (accepted !== undefined) {
-        if (typeof accepted !== 'boolean') {
-          throw new TypeError('controlExecutor must return a boolean or undefined');
+    const inputRpcId = `${this.#rpcIdPrefix}-steer-${randomUUID()}`;
+    const releaseInputOrigin = registerImInputOrigin(this.#interactionRegistry, inputRpcId);
+    try {
+      if (this.#controlExecutor) {
+        const accepted = this.#controlExecutor({
+          sessionId,
+          expectedTurn: ownership.turn,
+          promptRpcId: ownership.promptRpcId,
+          inputRpcId,
+          action: 'steer',
+          text,
+        });
+        if (accepted && typeof accepted.then === 'function') {
+          throw new TypeError('controlExecutor must return synchronously');
+        }
+        if (accepted !== undefined) {
+          if (typeof accepted !== 'boolean') {
+            throw new TypeError('controlExecutor must return a boolean or undefined');
+          }
+          if (!accepted) releaseInputOrigin();
+          return accepted;
         }
-        return accepted;
       }
+      await this.rpc('session.prompt', {
+        sessionId,
+        mode: 'steer',
+        content: [{ type: 'text', text }],
+        clientTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+      }, 30_000, { ...options, rpcId: inputRpcId });
+      return true;
+    } catch (error) {
+      releaseInputOrigin();
+      throw error;
     }
-    await this.rpc('session.prompt', {
-      sessionId,
-      mode: 'steer',
-      content: [{ type: 'text', text }],
-      clientTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-    }, 30_000, options);
-    return true;
   }
 
   #consumeInteractionOwnerships(sessionId, entries) {
@@ -1302,6 +1381,7 @@ export class HarnessClient {
     );
     const baselineSeq = Math.max(-1, ...(before.events ?? []).map(({ event }) => event.seq ?? -1));
     const promptRpcId = `${this.#rpcIdPrefix}-${randomUUID()}`;
+    const releasePromptInputOrigin = registerImInputOrigin(this.#interactionRegistry, promptRpcId);
     const tracker = new HarnessReplyTracker({ promptRpcId, afterSeq: baselineSeq });
     const interactionController = onInteraction || onInteractionResolved
       ? new AbortController()
@@ -1518,6 +1598,7 @@ export class HarnessClient {
         throw turnStoppedError();
       }
     } finally {
+      releasePromptInputOrigin();
       if (!promptAccepted || turnFinished) {
         for (const staged of stagedBatches) {
           try {

package/src/channels/shared/inbound-file.mjs

@@ -1,11 +1,40 @@
 import { createWriteStream } from 'node:fs';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, realpath, rm, writeFile } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 
 import { t } from './i18n.mjs';
 
 const FILES_DIRECTORY = join('.dsh-im', 'inbound');
+const RETENTIONS = new Set(['turn', 'persistent']);
+const DIRECTORY_TIMESTAMP_PATTERN = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})/;
+
+function padded(value) {
+  return String(value).padStart(2, '0');
+}
+
+/** Timestamp prefix (`yyyyMMdd-HHmmss-`) handed to mkdtemp for random suffixes. */
+function inboundDirectoryPrefix(now = new Date()) {
+  return `${now.getFullYear()}${padded(now.getMonth() + 1)}${padded(now.getDate())}`
+    + `-${padded(now.getHours())}${padded(now.getMinutes())}${padded(now.getSeconds())}-`;
+}
+
+/**
+ * Parse the local-time instant encoded in a staged inbound directory name,
+ * returning null for legacy `turn-` names and anything unparseable.
+ */
+export function parseInboundDirectoryName(name) {
+  if (typeof name !== 'string') return null;
+  const match = DIRECTORY_TIMESTAMP_PATTERN.exec(name);
+  if (!match) return null;
+  const [year, month, day, hour, minute, second] = match.slice(1).map(Number);
+  const date = new Date(year, month - 1, day, hour, minute, second);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day
+    || date.getHours() !== hour || date.getMinutes() !== minute || date.getSeconds() !== second) {
+    return null;
+  }
+  return date;
+}
 
 export class InboundFileError extends Error {
   constructor(code, message, userMessage = t('文件接收失败，请重新发送后再试。'), options = {}) {
@@ -97,7 +126,18 @@ export function prefetchInboundFiles(message, { signal } = {}) {
 export async function stageInboundFiles(message, {
   workspace,
   signal,
+  retention = 'turn',
+  onStagedDirectory = null,
 } = {}) {
+  if (!RETENTIONS.has(retention)) {
+    throw new InboundFileError(
+      'inbound-file-retention-invalid',
+      `Unknown inbound file retention: ${String(retention)}`,
+    );
+  }
+  if (onStagedDirectory !== null && typeof onStagedDirectory !== 'function') {
+    throw new TypeError('onStagedDirectory must be a function');
+  }
   const sources = fileSources(message);
   if (sources.length === 0) return null;
   if (typeof workspace !== 'string' || !isAbsolute(workspace)) {
@@ -110,7 +150,10 @@ export async function stageInboundFiles(message, {
   signal?.throwIfAborted();
   const root = resolve(workspace, FILES_DIRECTORY);
   await mkdir(root, { recursive: true, mode: 0o700 });
-  const directory = await mkdtemp(join(root, 'turn-'));
+  const directory = await mkdtemp(join(root, inboundDirectoryPrefix()));
+  // Register the batch before any file is written so a concurrent TTL=0
+  // sweep can never observe the directory as untracked mid-staging.
+  onStagedDirectory?.(directory);
   const files = [];
 
   try {
@@ -177,7 +220,11 @@ export async function stageInboundFiles(message, {
     }
     return Object.freeze({
       files: Object.freeze(files),
+      directory,
+      retention,
       async cleanup() {
+        // Persistent retention leaves the directory to the global TTL sweeper.
+        if (retention !== 'turn') return;
         await rm(directory, { recursive: true, force: true });
       },
     });
@@ -187,6 +234,74 @@ export async function stageInboundFiles(message, {
   }
 }
 
+/**
+ * Delete expired staged inbound directories under one workspace. Only
+ * directories whose names parse as `yyyyMMdd-HHmmss` timestamps are managed;
+ * legacy `turn-` names and anything unparseable stay untouched. Directories
+ * reported as tracked by an in-flight turn are always skipped.
+ */
+export async function sweepInboundAttachments(workspace, ttlHours, {
+  now = () => new Date(),
+  isTracked,
+} = {}) {
+  if (typeof workspace !== 'string' || !workspace) {
+    throw new TypeError('sweepInboundAttachments requires a workspace');
+  }
+  // An unparsable TTL must never widen into unconditional deletion.
+  if (ttlHours !== 0 && !(Number.isInteger(ttlHours) && ttlHours > 0)) {
+    return { deleted: 0 };
+  }
+  const root = resolve(workspace, FILES_DIRECTORY);
+  let canonicalWorkspace;
+  let canonicalRoot;
+  try {
+    [canonicalWorkspace, canonicalRoot] = await Promise.all([
+      realpath(workspace),
+      realpath(root),
+    ]);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { deleted: 0 };
+    throw error;
+  }
+  const rootInWorkspace = relative(canonicalWorkspace, canonicalRoot);
+  if (!rootInWorkspace || rootInWorkspace.startsWith('..') || isAbsolute(rootInWorkspace)) {
+    throw new InboundFileError(
+      'inbound-file-root-outside-workspace',
+      'The inbound attachment directory does not resolve inside the Harness Session workspace.',
+    );
+  }
+  let entries;
+  try {
+    entries = await readdir(canonicalRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { deleted: 0 };
+    throw error;
+  }
+  const current = now();
+  let deleted = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const stagedAt = parseInboundDirectoryName(entry.name);
+    if (stagedAt === null) continue;
+    const directory = join(root, entry.name);
+    const canonicalDirectory = join(canonicalRoot, entry.name);
+    if (typeof isTracked === 'function'
+      && (isTracked(directory) || (directory !== canonicalDirectory && isTracked(canonicalDirectory)))) {
+      continue;
+    }
+    const ageHours = (current - stagedAt) / 3_600_000;
+    if (ttlHours === 0 || ageHours >= ttlHours) {
+      try {
+        await rm(canonicalDirectory, { recursive: true, force: true });
+        deleted += 1;
+      } catch {
+        // One undeletable directory must not abort the remaining sweep.
+      }
+    }
+  }
+  return { deleted };
+}
+
 export function appendInboundFilesToPrompt(prompt, staged) {
   if (!staged?.files?.length) return prompt;
   const manifest = [

package/src/channels/shared/inbound-ttl-store.mjs

@@ -0,0 +1,110 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+import { DEFAULT_INBOUND_TTL_HOURS, normalizeInboundTtlHours } from './inbound-ttl.mjs';
+
+const DOCUMENT_VERSION = 1;
+// Fail-safe TTL for documents that exist but cannot be trusted (damage or an
+// unknown future version, e.g. after a rollback). TTL 0 would sweep every
+// untracked directory on the next pass, so keep-forever is the safe fallback.
+const UNREADABLE_DOCUMENT_TTL_HOURS = -1;
+
+function invalidTtlError() {
+  const error = new Error('Invalid inbound attachment TTL hours.');
+  error.code = 'inbound-ttl-invalid';
+  return error;
+}
+
+// Mirrors the atomic settings writes of the bot workspace store and the
+// update service: create a private temporary file, then rename it into place.
+async function writeSettingsDocument(path, document) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}
+
+/** Durable host-side settings for the global inbound attachment TTL. */
+export class InboundTtlStore {
+  #path;
+  #ttlHours = DEFAULT_INBOUND_TTL_HOURS;
+
+  constructor(path) {
+    if (typeof path !== 'string' || !path) throw new TypeError('inbound TTL store path is required');
+    this.#path = path;
+  }
+
+  /**
+   * A missing file means first run (default TTL). A damaged or future
+   * document falls back to keep-forever so an unreadable intent can never
+   * widen into deletion; the value stays visible in the settings UI.
+   */
+  async load() {
+    let raw;
+    try {
+      raw = await readFile(this.#path, 'utf8');
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      this.#ttlHours = DEFAULT_INBOUND_TTL_HOURS;
+      await this.#removeStaleTemporaries();
+      return this;
+    }
+    this.#ttlHours = this.#readTtlHours(raw) ?? UNREADABLE_DOCUMENT_TTL_HOURS;
+    await this.#removeStaleTemporaries();
+    return this;
+  }
+
+  // Crash leftovers from an interrupted atomic write are unreferenced by
+  // anyone; remove them so the settings directory stays clean.
+  async #removeStaleTemporaries() {
+    const directory = dirname(this.#path);
+    const prefix = `${basename(this.#path)}.`;
+    try {
+      const entries = await readdir(directory);
+      await Promise.all(entries
+        .filter((name) => name.startsWith(prefix) && name.endsWith('.tmp'))
+        .map((name) => unlink(join(directory, name)).catch(() => {})));
+    } catch {
+      // A missing directory or concurrent removal is fine; cleanup is best-effort.
+    }
+  }
+
+  #readTtlHours(raw) {
+    let document;
+    try {
+      document = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+    if (!document || typeof document !== 'object' || Array.isArray(document)) return null;
+    if (document.version !== DOCUMENT_VERSION) return null;
+    if (document.inboundAttachmentTtlHours === undefined) return DEFAULT_INBOUND_TTL_HOURS;
+    return normalizeInboundTtlHours(document.inboundAttachmentTtlHours);
+  }
+
+  getTtlHours() {
+    return this.#ttlHours;
+  }
+
+  async setTtlHours(value) {
+    const ttlHours = normalizeInboundTtlHours(value);
+    if (ttlHours === null) throw invalidTtlError();
+    await writeSettingsDocument(this.#path, {
+      version: DOCUMENT_VERSION,
+      inboundAttachmentTtlHours: ttlHours,
+    });
+    this.#ttlHours = ttlHours;
+    return ttlHours;
+  }
+}

package/src/channels/shared/inbound-ttl.mjs

@@ -0,0 +1,22 @@
+export const DEFAULT_INBOUND_TTL_HOURS = 168;
+export const INBOUND_TTL_MAX_HOURS = 8760;
+
+const INTEGER_STRING = /^[+-]?\d+$/;
+
+/**
+ * Normalize a global inbound attachment TTL. Valid values are -1 (keep
+ * forever), 0 (delete once the owning turn ends), and whole hours 1..8760.
+ * Integer strings are tolerated; every other input returns null.
+ */
+export function normalizeInboundTtlHours(value) {
+  let candidate = value;
+  if (typeof candidate === 'string') {
+    const trimmed = candidate.trim();
+    if (!INTEGER_STRING.test(trimmed)) return null;
+    candidate = Number(trimmed);
+  }
+  if (typeof candidate !== 'number' || !Number.isInteger(candidate)) return null;
+  if (candidate === -1) return -1;
+  if (candidate >= 0 && candidate <= INBOUND_TTL_MAX_HOURS) return candidate;
+  return null;
+}

package/src/channels/shared/model-setting.mjs

@@ -0,0 +1,110 @@
+const MAX_PROVIDER_ID_LENGTH = 256;
+const MAX_MODEL_ID_LENGTH = 1_024;
+const MAX_LABEL_LENGTH = 256;
+const UNSAFE_DISPLAY_TEXT = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu;
+const UNSAFE_ID_TEXT = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+
+function cleanId(value, maxLength) {
+  if (typeof value !== 'string') return '';
+  const id = value.trim();
+  if (!id || id.length > maxLength || UNSAFE_ID_TEXT.test(id)) return '';
+  return id;
+}
+
+function cleanLabel(value, fallback) {
+  if (typeof value !== 'string') return fallback;
+  const label = value.replace(UNSAFE_DISPLAY_TEXT, ' ').replace(/\s+/gu, ' ').trim();
+  return label ? label.slice(0, MAX_LABEL_LENGTH) : fallback;
+}
+
+export const EMPTY_MODEL_CATALOG = Object.freeze({
+  groups: Object.freeze([]),
+  failures: Object.freeze([]),
+});
+
+export function normalizeModelSelection(value) {
+  if (value == null) return null;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const provider = cleanId(value.provider, MAX_PROVIDER_ID_LENGTH);
+  const model = cleanId(value.model, MAX_MODEL_ID_LENGTH);
+  return provider && model ? { provider, model } : null;
+}
+
+export function validateModelSelection(value) {
+  if (value == null || value === '') return null;
+  const selection = normalizeModelSelection(value);
+  if (!selection) {
+    const error = new Error('模型无效。');
+    error.code = 'model-selection-invalid';
+    throw error;
+  }
+  return selection;
+}
+
+export function sameModelSelection(left, right) {
+  return left?.provider === right?.provider && left?.model === right?.model;
+}
+
+export function modelSelectionId(value) {
+  const selection = normalizeModelSelection(value);
+  return selection ? `${selection.provider}/${selection.model}` : '';
+}
+
+export function normalizeModelCatalog(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { groups: [], failures: [] };
+  }
+  const groups = [];
+  const seen = new Set();
+  for (const candidate of Array.isArray(value.groups) ? value.groups : []) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) continue;
+    const provider = cleanId(candidate.id, MAX_PROVIDER_ID_LENGTH);
+    if (!provider) continue;
+    const models = [];
+    for (const entry of Array.isArray(candidate.models) ? candidate.models : []) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+      const model = cleanId(entry.id, MAX_MODEL_ID_LENGTH);
+      if (!model) continue;
+      const key = `${provider}\u0000${model}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      models.push({
+        id: model,
+        name: cleanLabel(entry.name, model),
+      });
+    }
+    if (models.length > 0) {
+      groups.push({
+        id: provider,
+        name: cleanLabel(candidate.name, provider),
+        models,
+      });
+    }
+  }
+  const failures = [];
+  for (const candidate of Array.isArray(value.failures) ? value.failures : []) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) continue;
+    const id = cleanId(candidate.id, MAX_PROVIDER_ID_LENGTH);
+    if (!id) continue;
+    failures.push({ id, name: cleanLabel(candidate.name, id) });
+  }
+  return { groups, failures };
+}
+
+export function modelCatalogHas(catalog, selection) {
+  const normalized = normalizeModelSelection(selection);
+  if (!normalized) return false;
+  return normalizeModelCatalog(catalog).groups.some(
+    (group) => group.id === normalized.provider
+      && group.models.some((model) => model.id === normalized.model),
+  );
+}
+
+export async function listModelCatalog(harness, options = {}) {
+  try {
+    if (typeof harness?.listModels !== 'function') return normalizeModelCatalog(null);
+    return normalizeModelCatalog(await harness.listModels(options));
+  } catch {
+    return normalizeModelCatalog(null);
+  }
+}