@jingyi0605/codingns4dsh 0.2.1-rc.2 → 0.2.1-rc.4

package/data/build/dist/host/cli-adapters/feature.js

@@ -21,9 +21,15 @@ import { CodingNsCliSessionStore } from './session-store.js';
 import { CodingNsDshMessageProjector } from './dsh-message-projector.js';
 import { CommandCodeSubscriptionService } from './command-code-subscription.js';
 import { ProviderSubscriptionService } from './provider-subscription.js';
-import { MagpieUsageService, magpieAgentForAdapter } from './magpie-usage.js';
+import { attachMagpieSessionNames, MagpieUsageService, magpieAgentForAdapter } from './magpie-usage.js';
+import { readDshProviderSource } from './dsh-config.js';
+import { MagpieManagementService } from './magpie-management.js';
+import { MagpieWebService } from './magpie-web.js';
+import { MagpieUpdateService } from './magpie-update.js';
+import { MagpieInstallDetectionService, normalizeCustomCommand } from './magpie-detection.js';
 import { createMagpieSessionRouting } from './magpie-session-routing.js';
 import { normalizeSubagentBridgeSettings, normalizeSubscriptionUsageSettings } from '../../shared/contracts/config.js';
+import { CodingNsRpcError } from '../rpc-table.js';
 import { setAdapterRegistry } from './registry-holder.js';
 import { createDshVirtualProviderRegistration } from './dsh-virtual-providers.js';
 import { dispatchBridgeSubagent } from '../cli-bridge/dispatch.js';
@@ -49,6 +55,7 @@ import { sessionPromptScope } from '../../dsh-capabilities/host/session-prompt-a
 import { createSessionPromptTranslation } from '../features/session-prompt-translation.js';
 import { codexPerformanceProjection } from './codex-performance-projection.js';
 import { grokContextProjection, grokPerformanceProjection } from './grok-performance-projection.js';
+import { countSessionTurnSteps } from './session-performance-projection.js';
 import { fromCliProviderId, toCliProviderId } from '../../shared/cli-provider-route.js';
 import { DshAgentTeamAdapter } from '../../dsh-capabilities/host/agent-team-adapter.js';
 import { CodingNsTeamDispatcher } from '../cli-bridge/team-dispatch.js';
@@ -80,8 +87,55 @@ export function createCliAdaptersFeature(options = {}) {
                 const timeoutMs = normalizeSubscriptionUsageSettings(settings?.subscriptionUsage).timeoutSecs * 1000;
                 return new ProviderSubscriptionService({ commandCode: new CommandCodeSubscriptionService({ timeoutMs }), timeoutMs });
             };
-            let subscriptions = buildSubscriptions(context.services.settings?.get());
-            const magpieUsage = options.magpieUsage ?? new MagpieUsageService({ lifetimeSignal: lifetime.signal });
+            let subscriptions = options.subscriptions ?? buildSubscriptions(context.services.settings?.get());
+            let magpieDetection = options.magpieDetection ?? new MagpieInstallDetectionService(options.magpieDetectionOptions);
+            // 最近一次可用的 Magpie 入口；探测会随用户指定的路径变化而重建，Web 服务总是读最新值。
+            let magpieCommand = null;
+            let magpieVersion = null;
+            const magpieWeb = options.magpieWeb ?? new MagpieWebService({ startupCommand: () => magpieCommand });
+            const magpieUsage = options.magpieUsage ?? new MagpieUsageService({ lifetimeSignal: lifetime.signal, webApi: magpieWeb });
+            const magpieManagement = options.magpieManagement ?? new MagpieManagementService({ webApi: magpieWeb });
+            const magpieUpdates = options.magpieUpdates ?? new MagpieUpdateService({ webApi: magpieWeb, version: () => magpieVersion });
+            let magpieWebDesired = false;
+            let magpieWebSync = Promise.resolve();
+            const scheduleMagpieWebSync = (enabled) => {
+                magpieWebDesired = enabled;
+                if (!enabled) {
+                    magpieUpdates.stopBackgroundChecks();
+                    void magpieWeb.stop().catch(() => undefined);
+                }
+                const next = magpieWebSync.then(async () => {
+                    if (magpieWebDesired !== enabled)
+                        return;
+                    if (!enabled) {
+                        await magpieWeb.stop();
+                        return;
+                    }
+                    try {
+                        await magpieWeb.start();
+                        magpieUpdates.startBackgroundChecks();
+                    }
+                    catch (error) {
+                        console.warn('codingns4dsh: Magpie Web startup failed; the next Web API request will retry', error);
+                    }
+                });
+                magpieWebSync = next.catch(() => undefined);
+            };
+            // 设置里可能保留了“已启用”，但本机没有可用 Magpie（换机、卸载或安装损坏）。
+            // 这种情况下不拉起 Magpie Web，等用户安装后重新检测再启用。
+            let magpieInstalled = await magpieDetection.detect().then((detection) => {
+                const usable = MagpieInstallDetectionService.isUsable(detection);
+                magpieCommand = usable ? detection.command : null;
+                magpieVersion = usable ? detection.version : null;
+                return usable;
+            }, () => false);
+            scheduleMagpieWebSync(context.services.settings?.get().modules.magpieManagement === true && magpieInstalled);
+            context.resources.add(async () => {
+                magpieWebDesired = false;
+                await magpieWeb.stop();
+                await magpieWebSync;
+                await magpieWeb.dispose();
+            });
             let subscriptionSettings = JSON.stringify(context.services.settings?.get().subscriptionUsage ?? null);
             // 注入的 registry 自带 SessionStore；只有自建时才有本地 store 变量。
             const sessionStore = options.registry?.sessionRecords
@@ -334,11 +388,17 @@ export function createCliAdaptersFeature(options = {}) {
                         const subscription = readSubscriptionRequest(payload);
                         const requestSignal = signal ?? lifetime.signal;
                         const session = subscription.sessionId === undefined ? undefined : registry.getSession(subscription.sessionId);
-                        if (session !== undefined && session.adapterId === subscription.adapterId) {
+                        if (context.services.settings?.get().modules.magpieManagement === true
+                            && session !== undefined && session.adapterId === subscription.adapterId) {
                             const magpie = await magpieUsage.read(session, requestSignal, subscription.includeRoute, subscription.sessionId);
                             requestSignal.throwIfAborted();
-                            if (magpie !== null)
-                                return { providerUsage: null, magpie };
+                            const snapshot = magpie ?? (subscription.sessionId === undefined
+                                ? null
+                                : await pendingMagpieUsage(magpieUsage, nativeSessions, subscription.sessionId, session, requestSignal));
+                            if (snapshot !== null) {
+                                const sessionName = subscription.sessionId === undefined ? undefined : readDshSessionDisplayName(subscription.sessionId, sessionStore, nativeSessions);
+                                return { providerUsage: null, magpie: sessionName === undefined ? snapshot : { ...snapshot, sessionName } };
+                            }
                         }
                         requestSignal.throwIfAborted();
                         const providerUsage = await subscriptions.read(subscription.adapterId, subscription.providerId, subscription.modelId);
@@ -365,6 +425,67 @@ export function createCliAdaptersFeature(options = {}) {
                     default: throw new Error(`未知 CLI RPC: cli/${action}`);
                 }
             }));
+            context.resources.add(context.services.rpc.register('magpie', async (action, payload, rpcContext) => {
+                const rpcSignal = asRecord(rpcContext)?.signal;
+                const signal = isAbortSignal(rpcSignal) ? rpcSignal : lifetime.signal;
+                // 安装探测本身就是启用前的判断依据，因此不要求模块已启用。
+                if (action === 'management/detection') {
+                    const request = readMagpieDetectionRequest(payload);
+                    const force = readMagpieDetectionForce(payload);
+                    // A custom path is request-scoped; it must not poison later automatic detection.
+                    const customCommand = normalizeCustomCommand(request.commandPath);
+                    const detectionService = customCommand === null
+                        ? magpieDetection
+                        : new MagpieInstallDetectionService({ ...options.magpieDetectionOptions, customCommand });
+                    const detection = await detectionService.detect(customCommand === null ? {} : { commandPath: customCommand }, { force: force || customCommand !== null });
+                    magpieCommand = MagpieInstallDetectionService.isUsable(detection) ? detection.command : null;
+                    magpieVersion = MagpieInstallDetectionService.isUsable(detection) ? detection.version : null;
+                    return detection;
+                }
+                if (context.services.settings?.get().modules.magpieManagement !== true) {
+                    throw new CodingNsRpcError('CODINGNS_MAGPIE_DISABLED', 'Magpie management is disabled');
+                }
+                switch (action) {
+                    case 'usage/dashboard': {
+                        const dashboard = await magpieUsage.readDashboard(readMagpieDashboardPeriod(payload), signal);
+                        return attachMagpieSessionNames(dashboard, await magpieSessionNameBindings(sessionStore, nativeSessions, signal));
+                    }
+                    case 'usage/dashboard/stream': {
+                        const input = asRecord(payload);
+                        const period = readMagpieDashboardPeriod(payload);
+                        const force = input?.force === true;
+                        return streamMagpieDashboard(magpieUsage, period, signal, force, sessionStore, nativeSessions);
+                    }
+                    case 'usage/requests': {
+                        const request = readMagpieRequestOptions(payload);
+                        const page = await magpieUsage.readRequestPage(request, signal);
+                        if (page === null || request.sessionId === undefined)
+                            return page;
+                        return {
+                            ...page,
+                            sessionMetrics: readMagpieSessionMetrics(sessionStore, nativeSessions, request.sessionId, request.sessionIds),
+                        };
+                    }
+                    case 'management/snapshot':
+                        return magpieManagement.readSnapshot(signal);
+                    case 'management/provider/update':
+                        return magpieManagement.updateProvider(payload, signal);
+                    case 'management/group/update':
+                        return magpieManagement.updateGroup(payload, signal);
+                    case 'management/account/update':
+                        return magpieManagement.updateAccount(payload, signal);
+                    case 'update/status':
+                        return magpieUpdates.readStatus(signal);
+                    case 'update/notes':
+                        return magpieUpdates.readNotes(signal);
+                    case 'update/check':
+                        return magpieUpdates.checkForUpdate(signal);
+                    case 'update/install':
+                        return magpieUpdates.installUpdate(payload, signal);
+                    default:
+                        throw new CodingNsRpcError('CODINGNS_RPC_NOT_FOUND', `Unknown Magpie RPC: ${action}`);
+                }
+            }));
             // 外部 CLI 子代理托管：开启时启动本机回环桥接，把外部 CLI 的子代理调用
             // 转投成 DSH 原生可续子会话；关闭或模块停用时收回端口并清空驱动句柄。
             let bridgeServer;
@@ -435,6 +556,17 @@ export function createCliAdaptersFeature(options = {}) {
                         subscriptions = buildSubscriptions(next);
                     }
                     syncSubagentBridgeSettings(next.subagentBridge);
+                    const magpieWanted = next.modules.magpieManagement === true;
+                    // 只在“需要启动”时重新探测；停用时立即回收，退出探测的旧结果不覆盖新状态。
+                    void (magpieWanted && !magpieInstalled
+                        ? magpieDetection.detect({}, { force: true }).then(detection => MagpieInstallDetectionService.isUsable(detection), () => false)
+                        : Promise.resolve(magpieInstalled)).then((installed) => {
+                        magpieInstalled = installed;
+                        if (next.modules.magpieManagement !== true)
+                            scheduleMagpieWebSync(false);
+                        else if (installed)
+                            scheduleMagpieWebSync(true);
+                    });
                 }));
             }
             const events = context.services.events;
@@ -684,6 +816,7 @@ export function createCliAdaptersFeature(options = {}) {
                 // Close native interaction cards before unloading their provider transports.
                 lifetime.abort();
                 updates.dispose();
+                magpieUpdates.dispose();
                 await management.dispose();
                 await registry.dispose();
                 await sessionStore.flush();
@@ -968,12 +1101,25 @@ function normalizeDshModelGroup(value) {
 /**
  * DSH 原生 Provider 可能只返回一个 finish(stop)。不能把这个空回合当作成功，
  * 否则 Session 会落下一条空 assistant/message，用户只能看到“一秒结束”。
+ *
+ * error finish 携带 Provider 的真实失败原因（状态码、上游错误消息、错误码），
+ * 必须原样透传：替换成统一文案会把 400/429/凭证失效等不同故障折叠成同一句
+ * “未返回任何有效事件”，既无法排查也不可分类告警。统一兜底文案只用于一种
+ * 情形——流以 stop（或无 finish）干净结束且没有任何有效事件，此时没有任何
+ * 原始错误可透传。
  */
 async function* guardDshNativeStream(next) {
     let meaningful = false;
     const terminal = [];
     for await (const chunk of next()) {
         if (isDshFinishChunk(chunk)) {
+            // error finish 本身就是“有效事件”：立即透传，并标记 meaningful，
+            // 让此前缓冲的非 error finish（正常情况下不会出现）也在收尾时放出。
+            if (isDshErrorFinishChunk(chunk)) {
+                meaningful = true;
+                yield chunk;
+                continue;
+            }
             terminal.push(chunk);
             continue;
         }
@@ -1002,6 +1148,11 @@ function isDshFinishChunk(value) {
     const record = asRecord(value);
     return record?.type === 'finish';
 }
+/** error finish（reason.kind === 'error'）携带 Provider 的原始失败，是必须透传的有效事件。 */
+function isDshErrorFinishChunk(value) {
+    const record = asRecord(value);
+    return record?.type === 'finish' && asRecord(record.reason)?.kind === 'error';
+}
 function isMeaningfulDshChunk(value) {
     const record = asRecord(value);
     if (record === null)
@@ -1386,6 +1537,105 @@ function nativePreStepContext(translation, registry, sessionId, nativeSessions)
         translationEnabled: session.translationEnabled ?? translation.nativeEnabled === true,
     };
 }
+function readOptionalText(value) {
+    return typeof value === 'string' ? value.trim() || undefined : undefined;
+}
+/** 原生 Provider 选中的模型，用于在 Magpie 会话身份可读之前判断该模型是否由 Magpie 提供。 */
+function readNativeModelSelection(nativeSessions, sessionId) {
+    if (nativeSessions === undefined)
+        return undefined;
+    let session;
+    try {
+        session = nativeSessions.get(sessionId);
+    }
+    catch {
+        return undefined;
+    }
+    const root = asRecord(session);
+    const selection = asRecord(root?.modelSelection) ?? asRecord(asRecord(asRecord(root?.record)?.rows)?.modelSelection);
+    const value = asRecord(selection?.val) ?? selection;
+    // 待用的 pending/next 优先；lastUsed 可能仍描述上一个模型。
+    for (const candidate of [asRecord(value?.pending), asRecord(value?.next), asRecord(value?.lastUsed)]) {
+        const modelId = readOptionalText(candidate?.model);
+        if (modelId === undefined)
+            continue;
+        const providerId = readOptionalText(candidate?.provider);
+        return providerId === undefined ? { modelId } : { providerId, modelId };
+    }
+    return undefined;
+}
+/** Magpie 网关只监听本机回环；Provider 指向这里时才算 Magpie 自己的路由。 */
+const MAGPIE_GATEWAY_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+function isMagpieGateway(baseUrl) {
+    try {
+        const target = new URL(baseUrl);
+        // 端口由 `magpie web` 绑定（默认 3425），配置里改端口也应视为同一网关，
+        // 因此这里只要求回环地址，不再硬编码端口。
+        return MAGPIE_GATEWAY_HOSTS.has(target.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Provider ID 本身可能是任意用户命名，因此先看 DSH 配置里的 baseURL；
+ * 配置读不到时只接受与 `readDshDefaultProvider()` 相同的 Magpie 名称约定。
+ */
+function isMagpieGatewayProvider(providerId) {
+    const source = readDshProviderSource(providerId);
+    if (source !== null)
+        return isMagpieGateway(source.baseUrl);
+    return /^magpie(?:[-_.].*)?$/iu.test(providerId);
+}
+/**
+ * 读到用量之后仍然要判断「这个模型是不是 Magpie 的」。
+ *
+ * `magpieUsage.read()` 只有在会话身份（Provider 会话 ID 或 DSH 会话 ID）已经出现在
+ * Magpie 账本里时才返回快照。新会话的首个请求可能还没被 Magpie Web 记账，或者两边的
+ * 会话 ID 在滚动升级期间并不相等，这时返回 null 会让 Host 直接回退到官方余量。
+ * 只有确认模型由 Magpie 提供时才下发占位快照，避免官方数字抢占首屏。
+ */
+async function pendingMagpieUsage(magpie, nativeSessions, sessionId, session, signal) {
+    const agent = magpieAgentForAdapter(session.adapterId);
+    const modelId = session.modelId?.trim();
+    if (agent === null || modelId === undefined || modelId === '')
+        return null;
+    try {
+        const selectedProviderId = session.providerId?.trim();
+        const providerId = selectedProviderId === undefined || selectedProviderId === ''
+            ? readNativeModelSelection(nativeSessions, sessionId)?.providerId
+            : selectedProviderId;
+        if (providerId === undefined || !isMagpieGatewayProvider(providerId))
+            return null;
+        const confirmed = await magpie.readModelMetadata(session.adapterId, modelId, signal);
+        signal.throwIfAborted();
+        return confirmed === null ? null : pendingMagpieSnapshot(agent, modelId);
+    }
+    catch {
+        // 目录不可读、超时或请求被取消：保持原有回退语义，不伪造 Magpie 用量。
+        return null;
+    }
+}
+/** Magpie 已经确认提供该模型、但会话身份还读不到时下发的占位快照。 */
+function pendingMagpieSnapshot(agent, modelId) {
+    const capturedAt = new Date().toISOString();
+    return {
+        agent,
+        modelId,
+        capturedAt,
+        usageStatus: 'unavailable',
+        aggregate: null,
+        sessionId: null,
+        session: null,
+        routeStatus: 'not-requested',
+        route: null,
+        upstreamProvider: null,
+        upstreamProviders: [],
+        // 客户端据此在 3 秒内带路由补读，而不是停留在官方余额上。
+        quotaStatus: 'provider-unavailable',
+        quotas: [],
+    };
+}
 /** 读取原生会话 header；测试替身或会话尚未装载时返回 undefined。 */
 function readNativeSessionHeader(nativeSessions, sessionId) {
     if (nativeSessions === undefined)
@@ -1881,6 +2131,188 @@ function findCwdInValue(value, depth) {
     }
     return undefined;
 }
+function readMagpieDashboardPeriod(payload) {
+    const value = asRecord(payload)?.period;
+    if (value === 'today' || value === 'week' || value === 'month' || value === 'all')
+        return value;
+    throw new TypeError('Magpie usage period must be today, week, month, or all');
+}
+async function* streamMagpieDashboard(service, period, signal, force, sessionStore, nativeSessions) {
+    const names = magpieSessionNameBindings(sessionStore, nativeSessions, signal).catch(() => []);
+    let latest;
+    for await (const chunk of service.readDashboardStream(period, signal, force)) {
+        latest = chunk.dashboard;
+        yield chunk;
+    }
+    if (latest !== undefined) {
+        const named = attachMagpieSessionNames(latest, await names);
+        if (named !== latest)
+            yield { part: 'sessions', dashboard: named, stale: false };
+    }
+}
+/** 探测载荷只接受可选入口路径；其余字段一律忽略，避免把参数带进命令行。 */
+function readMagpieDetectionRequest(payload) {
+    const record = asRecord(payload);
+    if (record === null || typeof record.commandPath !== 'string')
+        return {};
+    const commandPath = record.commandPath.trim();
+    return commandPath === '' ? {} : { commandPath };
+}
+/** `force` 只在用户主动重新检测时出现；缺省复用短期探测结果。 */
+function readMagpieDetectionForce(payload) {
+    return asRecord(payload)?.force === true;
+}
+function readMagpieRequestOptions(payload) {
+    const record = asRecord(payload);
+    if (record === null)
+        throw new TypeError('Magpie request page must be an object');
+    const period = readMagpieDashboardPeriod(record);
+    const offset = record.offset === undefined ? 0 : record.offset;
+    const limit = record.limit === undefined ? 50 : record.limit;
+    if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0 || offset > 1_000_000) {
+        throw new TypeError('Magpie request offset is out of bounds');
+    }
+    if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+        throw new TypeError('Magpie request limit must be between 1 and 100');
+    }
+    const sessionId = readOptionalMagpieIdentity(record.sessionId, 512);
+    const sessionIds = record.sessionIds === undefined
+        ? undefined
+        : readOptionalMagpieIdentityList(record.sessionIds, 16, 512);
+    const sessionAgent = readOptionalMagpieIdentity(record.sessionAgent, 64);
+    if ((sessionId === undefined) !== (sessionAgent === undefined)) {
+        throw new TypeError('Magpie session details require both sessionId and sessionAgent');
+    }
+    if (sessionIds !== undefined && sessionId === undefined) {
+        throw new TypeError('Magpie session IDs require a primary session ID');
+    }
+    if (sessionAgent !== undefined && !/^[a-z0-9][a-z0-9-]*$/u.test(sessionAgent)) {
+        throw new TypeError('Magpie session Agent is invalid');
+    }
+    return {
+        period,
+        offset,
+        limit,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        ...(sessionIds === undefined ? {} : { sessionIds }),
+        ...(sessionAgent === undefined ? {} : { sessionAgent }),
+    };
+}
+function readMagpieSessionMetrics(sessionStore, nativeSessions, sessionId, sessionIds) {
+    if (nativeSessions === undefined)
+        return null;
+    const identities = new Set([sessionId, ...(sessionIds ?? [])]);
+    const bindings = sessionStore.list({ includeArchived: true }).filter((record) => identities.has(record.dshSessionId) || (record.providerSessionId !== undefined && identities.has(record.providerSessionId)));
+    const direct = bindings.find((record) => record.dshSessionId === sessionId);
+    const boundSessionIds = [...new Set(bindings.map((record) => record.dshSessionId))];
+    if (direct === undefined && boundSessionIds.length > 1)
+        return null;
+    const dshSessionId = direct?.dshSessionId ?? boundSessionIds[0] ?? sessionId;
+    let session;
+    try {
+        session = nativeSessions.get(dshSessionId);
+    }
+    catch {
+        return null;
+    }
+    const snapshotEvents = asRecord(session)?.snapshotEvents;
+    if (typeof snapshotEvents !== 'function')
+        return null;
+    try {
+        const events = snapshotEvents.call(session);
+        return Array.isArray(events) ? countSessionTurnSteps(events) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readOptionalMagpieIdentity(value, maxLength) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new TypeError('Magpie session identity must be text');
+    const text = value.trim();
+    if (text === '' || text.length > maxLength || /[\u0000-\u001f\u007f]/u.test(text)) {
+        throw new TypeError('Magpie session identity is invalid');
+    }
+    return text;
+}
+function readOptionalMagpieIdentityList(value, maxItems, maxLength) {
+    if (!Array.isArray(value) || value.length > maxItems)
+        throw new TypeError('Magpie session IDs are invalid');
+    const values = value.map((item) => readOptionalMagpieIdentity(item, maxLength));
+    if (values.some((item) => item === undefined))
+        throw new TypeError('Magpie session IDs are invalid');
+    return [...new Set(values)];
+}
+async function magpieSessionNameBindings(sessionStore, nativeSessions, signal) {
+    const records = sessionStore.list({ includeArchived: true });
+    const bindings = [];
+    const knownSessionIds = new Set();
+    let nativeValues = nativeSessions?.list() ?? [];
+    if (nativeSessions?.listRemote !== undefined) {
+        try {
+            nativeValues = await nativeSessions.listRemote(signal);
+        }
+        catch {
+            signal?.throwIfAborted();
+        }
+    }
+    const nativeNames = new Map();
+    for (const value of nativeValues) {
+        const sessionId = nativeSessionId(value);
+        const name = readNativeSessionDisplayName(value);
+        if (sessionId !== undefined && name !== undefined)
+            nativeNames.set(sessionId, name);
+    }
+    for (const record of records) {
+        knownSessionIds.add(record.dshSessionId);
+        const name = nativeNames.get(record.dshSessionId) ?? readDshSessionDisplayName(record.dshSessionId, sessionStore, nativeSessions);
+        bindings.push({
+            dshSessionId: record.dshSessionId,
+            adapterId: record.adapterId,
+            ...(record.providerSessionId === undefined ? {} : { providerSessionId: record.providerSessionId }),
+            ...(name === undefined ? {} : { name }),
+        });
+    }
+    // Native DSH sessions do not always have a CodingNS session-index record. They
+    // still use the DSH session ID as Magpie's identity, so include their title
+    // only when no external adapter binding claims the same DSH session.
+    for (const value of nativeValues) {
+        const sessionId = nativeSessionId(value);
+        if (sessionId === undefined || knownSessionIds.has(sessionId))
+            continue;
+        const name = readNativeSessionDisplayName(value);
+        bindings.push({ dshSessionId: sessionId, adapterId: 'dsh', ...(name === undefined ? {} : { name }) });
+    }
+    return bindings;
+}
+function readDshSessionDisplayName(sessionId, sessionStore, nativeSessions) {
+    return readNativeSessionDisplayName(nativeSessions?.get(sessionId)) ?? cleanDisplayName(sessionStore.get(sessionId)?.title);
+}
+function readNativeSessionDisplayName(value) {
+    const root = asRecord(value);
+    if (root === null)
+        return undefined;
+    const projection = asRecord(root.projections) ?? asRecord(asRecord(root.record)?.projections);
+    const values = asRecord(projection?.values);
+    const record = asRecord(root.record);
+    const rows = asRecord(record?.rows);
+    const rowProjection = asRecord(rows?.projections);
+    const rowValues = asRecord(rowProjection?.values);
+    for (const candidate of [values?.title, rowValues?.title, root.title, root.name, root.displayName, record?.title, record?.name]) {
+        const title = cleanDisplayName(candidate);
+        if (title !== undefined)
+            return title;
+    }
+    return undefined;
+}
+function cleanDisplayName(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const name = value.trim().replace(/[\u0000-\u001f\u007f]/gu, '').slice(0, 240);
+    return name === '' ? undefined : name;
+}
 function asRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null; }
 function isRecord(value) { return asRecord(value) !== null; }
 function nativeSessionId(value) {