@jingyi0605/codingns4dsh 0.1.0

package/data/build/dist/shared/index.d.ts

@@ -0,0 +1,22 @@
+export { CODINGNS_CONTROL_BASE_URL_FIELD, CODINGNS_CONTROL_BASE_URLS_FIELD, CODINGNS_LAN_ACCESS_DSH_FIELD, CODINGNS_TERMINAL_ENHANCEMENT_FIELD, CODINGNS_WORKSPACE_SESSION_ENHANCEMENT_FIELD, CODINGNS_MODULES_FIELD, CODINGNS_SETTINGS_NAMESPACE, DEFAULT_CODINGNS_CONTROL_BASE_URL, DEFAULT_CODINGNS_CONTROL_BASE_URLS, DEFAULT_CODINGNS_SETTINGS, DEFAULT_TERMINAL_ENHANCEMENT_SETTINGS, DEFAULT_WORKSPACE_SESSION_ENHANCEMENT_SETTINGS, captureRestartFeatureStates, enabledFeatureNames, isFeatureDshVersionCompatible, isFeatureEnabled, type CodingNsSettings, type CodingNsCliAdapterPreference, type LanAccessDshSettings, type LanAccessDshLoginSettings, type LoginProtectionScopes, type RestartFeatureStates, type TerminalAppearanceSettings, type TerminalAppearanceTheme, type TerminalBindingScope, type TerminalCursorStyle, type TerminalEnhancementSettings, type TerminalProfileId, type WorkspaceSessionEnhancementSettings, } from './contracts/config.js';
+export type { FeatureContext, FeatureActivation, FeatureDescriptor, FeatureDisposer, FeatureModule, FeatureResourceScope, FeatureRuntime, FeatureState, FeatureUiDescriptor, } from './contracts/feature.js';
+export { CODINGNS_DSH_ERROR_CODES, CodingNsDshError, SUPPORTED_DSH_COMPATIBILITY, SUPPORTED_DSH_VERSION, assertSupportedDshVersion, type CodingNsDshErrorCode, } from './contracts/errors.js';
+export { CODINGNS_VERSION, DSH_COMPATIBILITY, DSH_PROTOCOL_VERSION, CODINGNS_DSH_VERSION_GLOBAL, DSH_TESTED_VERSION, DSH_VERSION, isDshVersionAtLeast, isLegacyDshVersion, isDshVersionCompatible, } from './contracts/version.js';
+export type { CodingNsRpcRequest, CodingNsStreamRequest, CodingNsTransport, CodingNsTransportErrorShape, CodingNsTransportGeneration, CodingNsTransportHooks, } from './contracts/transport.js';
+export { DSH_ENVELOPE_PROTOCOL, DSH_ENVELOPE_VERSION, DEFAULT_MAX_DSH_ENVELOPE_BYTES, DEFAULT_MAX_DSH_META_BYTES, decodeDshEnvelope, encodeDshEnvelope, validateDshEnvelope, type DshChannel, type DshEnvelope, type DshEnvelopeCodecOptions, type DshEnvelopeFlags, type DshHostScope, } from '../transport/dsh-envelope.js';
+export { CODINGNS_RPC_CHANNEL } from './contracts/transport.js';
+export type { CodingNsCliAdapterDescriptor, CodingNsCliAdapterId, CodingNsCliCapability, CodingNsAgentEvent, CodingNsAgentQuestion, CodingNsAgentQuestionResponse, CodingNsAgentToolEvent, CodingNsCliMessage, CodingNsCliModel, CodingNsCliModelCatalog, CodingNsCliModelGroup, CodingNsAgentPermissionResponse, CodingNsCliSessionConfig, CodingNsCliSessionRecord, CodingNsCliProviderSessionState, CodingNsCliSessionStatus, CodingNsSessionAdapterBinding, CodingNsCliTurnInput, } from './contracts/cli-adapter.js';
+export type { CommandCodeSubscriptionUsage, CommandCodeSubscriptionWindow, } from './contracts/command-code.js';
+export type { CliSubscriptionUsage, CliSubscriptionWindow, Sub2ApiDailyUsage, Sub2ApiModelUsage, Sub2ApiUsage, Sub2ApiUsagePoint, } from './contracts/subscription.js';
+export type { PeerHostRecord, PeerHostStatus, ResourceScopeDisposer, ResourceScopeInput, ResourceScopeRef, ResourceScopeSnapshot, } from './contracts/peer-host.js';
+export { ResourceScopeStaleError } from './contracts/peer-host.js';
+export { DEBUG_ERROR_CODES, DEBUG_RPC_ENDPOINTS, parseDebugMutationScope, parseDebugPtyLaunchRequest, parseDebugRpcScope, type DebugAiFallbackState, type DebugCompatibilityLevel, type DebugErrorCode, type DebugMutationScope, type DebugPortState, type DebugProcessInstance, type DebugProcessOwnership, type DebugPlanState, type DebugProxyProtocol, type DebugPtyLaunchRequest, type DebugRpcEndpoint, type DebugRpcScope, type DebugRuntimeMode, type DebugRuntimeState, } from './contracts/debug.js';
+export type { LanAccessDshConfig, LanAccessDshLoginConfig, LanAccessDshSnapshot, LanAccessDshState, } from './contracts/lan-access-dsh.js';
+export type { CodingNsTerminalCreateRequest, CodingNsTerminalEnvironment, CodingNsTerminalFrame, CodingNsTerminalRetentionFrame, CodingNsTerminalRuntimeType, CodingNsTerminalShell, CodingNsTerminalShellOption, CodingNsTerminalStatus, CodingNsTerminalState, CodingNsWebTerminalInfo, PersistentTerminalRecord, TerminalAttachmentRecord, TerminalOwnerScope, TerminalRecordIdentity, } from './contracts/terminal.js';
+export { EMPTY_DEBUG_CONFIG, parseDebugConfig, type DebugConfig, type DebugProfile, type DebugProxyConfig, type DebugRuntimeType, type DebugShell, } from './contracts/debug-config.js';
+export type { DshDeviceSummary, DshDeviceRegistrationRequest, DshDeviceRegistrationResponse, DshDeviceListResponse, DshDeviceHeartbeatResponse, DshRelayTicketRequest, DshRelayTicketResponse, DshRelayTicketLike, DshIceServer, DshDeviceCredentialRecord, } from './contracts/dsh-device.js';
+export type { TerminalLaunchProfile, TerminalProcessInstance, TerminalProcessLaunchRequest, TerminalProcessLaunchResult, TerminalProcessState, } from './contracts/terminal-process.js';
+export type { AccountProfile, AuthClientType, AuthDeviceManagementSnapshotDto, AuthDeviceViewDto, CodingNsAuthLoginResult, CodingNsAuthSessionSnapshot, CodingNsAuthStatus, HostBindRequest, HostBindResponse, HostBindingsResponse, HostLabelAvailabilityResponse, HostUnbindResponse, LoginByEmailRequest, TunnelBindingSummary, } from './contracts/auth.js';
+export type { RelayIceServer, RelaySignalingTicketRequest, RelaySignalingClientMessage, RelaySignalingServerMessage, RelaySignalingTicketResponse, } from './contracts/signaling.js';
+export type { DshHostStatus } from './contracts/host-status.js';
+//# sourceMappingURL=index.d.ts.map

package/data/build/dist/shared/index.js

@@ -0,0 +1,9 @@
+export { CODINGNS_CONTROL_BASE_URL_FIELD, CODINGNS_CONTROL_BASE_URLS_FIELD, CODINGNS_LAN_ACCESS_DSH_FIELD, CODINGNS_TERMINAL_ENHANCEMENT_FIELD, CODINGNS_WORKSPACE_SESSION_ENHANCEMENT_FIELD, CODINGNS_MODULES_FIELD, CODINGNS_SETTINGS_NAMESPACE, DEFAULT_CODINGNS_CONTROL_BASE_URL, DEFAULT_CODINGNS_CONTROL_BASE_URLS, DEFAULT_CODINGNS_SETTINGS, DEFAULT_TERMINAL_ENHANCEMENT_SETTINGS, DEFAULT_WORKSPACE_SESSION_ENHANCEMENT_SETTINGS, captureRestartFeatureStates, enabledFeatureNames, isFeatureDshVersionCompatible, isFeatureEnabled, } from './contracts/config.js';
+export { CODINGNS_DSH_ERROR_CODES, CodingNsDshError, SUPPORTED_DSH_COMPATIBILITY, SUPPORTED_DSH_VERSION, assertSupportedDshVersion, } from './contracts/errors.js';
+export { CODINGNS_VERSION, DSH_COMPATIBILITY, DSH_PROTOCOL_VERSION, CODINGNS_DSH_VERSION_GLOBAL, DSH_TESTED_VERSION, DSH_VERSION, isDshVersionAtLeast, isLegacyDshVersion, isDshVersionCompatible, } from './contracts/version.js';
+export { DSH_ENVELOPE_PROTOCOL, DSH_ENVELOPE_VERSION, DEFAULT_MAX_DSH_ENVELOPE_BYTES, DEFAULT_MAX_DSH_META_BYTES, decodeDshEnvelope, encodeDshEnvelope, validateDshEnvelope, } from '../transport/dsh-envelope.js';
+export { CODINGNS_RPC_CHANNEL } from './contracts/transport.js';
+export { ResourceScopeStaleError } from './contracts/peer-host.js';
+export { DEBUG_ERROR_CODES, DEBUG_RPC_ENDPOINTS, parseDebugMutationScope, parseDebugPtyLaunchRequest, parseDebugRpcScope, } from './contracts/debug.js';
+export { EMPTY_DEBUG_CONFIG, parseDebugConfig, } from './contracts/debug-config.js';
+//# sourceMappingURL=index.js.map

package/data/build/dist/transport/carrier.d.ts

@@ -0,0 +1,38 @@
+import { type DshTransportDebugLogger } from './debug.js';
+export declare const TUNNEL_DATA_CHANNEL_LABEL = "codingns-tunnel";
+/** DataChannel 单消息保守上限；实际对端协商值可能只有 256 KiB。 */
+export declare const DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES: number;
+export declare const DATA_CHANNEL_FRAGMENT_HEADER_BYTES = 20;
+export declare const DATA_CHANNEL_MAX_REASSEMBLY_BYTES: number;
+export interface CodingNsCarrier {
+    readonly state: 'connecting' | 'open' | 'closed';
+    send(data: Uint8Array): Promise<void>;
+    subscribe(listener: (data: Uint8Array) => void): () => void;
+    /** 物理 carrier 关闭时通知上层重建 generation；不会携带业务正文。 */
+    onClosed?(listener: (reason?: string) => void): () => void;
+    close(reason?: string): Promise<void>;
+}
+export interface DataChannelLike {
+    readonly label?: string;
+    readonly readyState: string;
+    binaryType?: string;
+    readonly bufferedAmount?: number;
+    bufferedAmountLowThreshold?: number;
+    send(data: ArrayBuffer | ArrayBufferView): void;
+    close(): void;
+    addEventListener(type: 'message' | 'close' | 'open' | 'bufferedamountlow', listener: (event: Event) => void): void;
+    removeEventListener(type: 'message' | 'close' | 'open' | 'bufferedamountlow', listener: (event: Event) => void): void;
+}
+export interface DataChannelCarrierOptions {
+    highWaterMark?: number;
+    lowWaterMark?: number;
+    backpressureTimeoutMs?: number;
+    debug?: DshTransportDebugLogger;
+    reassemblyTimeoutMs?: number;
+    maxReassemblyBytes?: number;
+}
+/** Host 侧剥离父仓库 relay-tunnel-wire 的首个 hello，随后只转发 DSH Envelope 二进制。 */
+export declare function createRelayTunnelHostCarrier(base: CodingNsCarrier, debug?: DshTransportDebugLogger): CodingNsCarrier;
+/** 将浏览器或 Node WebRTC DataChannel 包装为带背压的二进制 Carrier。 */
+export declare function createDataChannelCarrier(channel: DataChannelLike, options?: DataChannelCarrierOptions): CodingNsCarrier;
+//# sourceMappingURL=carrier.d.ts.map

package/data/build/dist/transport/carrier.js

@@ -0,0 +1,268 @@
+/** DataChannel 二进制 Carrier。所有上层数据必须是 Uint8Array。 */
+import { decodeFrame } from './frame.js';
+import { createDshTransportDebugLogger } from './debug.js';
+export const TUNNEL_DATA_CHANNEL_LABEL = 'codingns-tunnel';
+/** DataChannel 单消息保守上限；实际对端协商值可能只有 256 KiB。 */
+export const DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES = 64 * 1024;
+export const DATA_CHANNEL_FRAGMENT_HEADER_BYTES = 20;
+export const DATA_CHANNEL_MAX_REASSEMBLY_BYTES = 16 * 1024 * 1024;
+const DATA_CHANNEL_FRAGMENT_MAGIC = new Uint8Array([0x44, 0x53, 0x46, 0x01]);
+/** Host 侧剥离父仓库 relay-tunnel-wire 的首个 hello，随后只转发 DSH Envelope 二进制。 */
+export function createRelayTunnelHostCarrier(base, debug) {
+    const logger = debug ?? createDshTransportDebugLogger({ component: 'relay-carrier' });
+    let helloSeen = false;
+    let failed = false;
+    const listeners = new Set();
+    const unsubscribe = base.subscribe((data) => {
+        if (failed)
+            return;
+        if (!helloSeen) {
+            try {
+                const frame = decodeFrame(data);
+                if (frame?.type !== 'hello')
+                    throw new Error('Relay Tunnel 首帧必须是 hello');
+                helloSeen = true;
+                logger.log('relay.hello.received', { bytes: data.byteLength, frameType: frame.type });
+            }
+            catch (error) {
+                failed = true;
+                logger.log('relay.hello.invalid', { bytes: data.byteLength, error: error instanceof Error ? error.message : String(error) });
+                void base.close(error instanceof Error ? error.message : 'Relay Tunnel hello 无效');
+            }
+            return;
+        }
+        logger.log('carrier.receive', { bytes: data.byteLength });
+        for (const listener of [...listeners])
+            listener(data);
+    });
+    return {
+        get state() { return failed ? 'closed' : base.state; },
+        send(data) {
+            if (!helloSeen)
+                return Promise.reject(new Error('Relay Tunnel hello 尚未完成'));
+            logger.log('carrier.send', { bytes: data.byteLength });
+            return base.send(data);
+        },
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        onClosed(listener) { return base.onClosed?.(listener) ?? (() => undefined); },
+        async close(reason) { unsubscribe(); listeners.clear(); await base.close(reason); },
+    };
+}
+/** 将浏览器或 Node WebRTC DataChannel 包装为带背压的二进制 Carrier。 */
+export function createDataChannelCarrier(channel, options = {}) {
+    const logger = options.debug ?? createDshTransportDebugLogger({ component: 'data-channel' });
+    let state = channel.readyState === 'open' ? 'open' : 'connecting';
+    const listeners = new Set();
+    const closeListeners = new Set();
+    const high = options.highWaterMark ?? 1024 * 1024;
+    const low = options.lowWaterMark ?? 256 * 1024;
+    const timeoutMs = options.backpressureTimeoutMs ?? 30_000;
+    const reassemblyTimeoutMs = options.reassemblyTimeoutMs ?? 30_000;
+    const maxReassemblyBytes = options.maxReassemblyBytes ?? DATA_CHANNEL_MAX_REASSEMBLY_BYTES;
+    let chain = Promise.resolve();
+    let receiveChain = Promise.resolve();
+    let nextFragmentId = 0;
+    const fragments = new Map();
+    try {
+        channel.binaryType = 'arraybuffer';
+    }
+    catch { /* 某些 WebRTC 实现不允许修改 binaryType */ }
+    const clearFragments = () => {
+        for (const fragment of fragments.values())
+            clearTimeout(fragment.timer);
+        fragments.clear();
+    };
+    const onOpen = () => { state = 'open'; logger.log('data-channel.open', { label: channel.label ?? null }); };
+    let closeNotified = false;
+    const notifyClosed = (reason) => {
+        if (closeNotified)
+            return;
+        closeNotified = true;
+        for (const listener of [...closeListeners])
+            listener(reason);
+        closeListeners.clear();
+    };
+    const onClose = () => { state = 'closed'; clearFragments(); logger.log('data-channel.close', { label: channel.label ?? null }); notifyClosed('DataChannel closed'); listeners.clear(); };
+    const processBytes = (bytes, value) => {
+        if (!bytes) {
+            logger.log('carrier.receive.invalid', { dataType: Object.prototype.toString.call(value), valueType: typeof value });
+            return;
+        }
+        try {
+            const complete = acceptFragment(bytes);
+            if (complete === null)
+                return;
+            logger.log('carrier.receive', { bytes: complete.byteLength, physicalBytes: bytes.byteLength, prefix: bytesToHex(bytes.subarray(0, 8)) });
+            for (const listener of [...listeners])
+                listener(complete);
+        }
+        catch (error) {
+            logger.log('carrier.fragment.error', { physicalBytes: bytes.byteLength, prefix: bytesToHex(bytes.subarray(0, 8)), error: error instanceof Error ? error.message : String(error) });
+            state = 'closed';
+            clearFragments();
+            listeners.clear();
+            channel.close();
+        }
+    };
+    const onMessage = (event) => {
+        const value = event.data;
+        const result = toBytes(value);
+        if (!(result instanceof Promise)) {
+            processBytes(result, value);
+            return;
+        }
+        receiveChain = receiveChain.then(() => result).then((bytes) => processBytes(bytes, value)).catch((error) => {
+            logger.log('carrier.receive.error', { error: error instanceof Error ? error.message : String(error) });
+        });
+    };
+    channel.addEventListener('open', onOpen);
+    channel.addEventListener('close', onClose);
+    channel.addEventListener('message', onMessage);
+    const waitOpen = () => state === 'open' ? Promise.resolve() : new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { cleanup(); reject(new Error('等待 DataChannel open 超时')); }, timeoutMs);
+        const cleanup = () => { clearTimeout(timer); channel.removeEventListener('open', onReady); channel.removeEventListener('close', onFail); };
+        const onReady = () => { cleanup(); resolve(); };
+        const onFail = () => { cleanup(); reject(new Error('DataChannel 已关闭')); };
+        channel.addEventListener('open', onReady);
+        channel.addEventListener('close', onFail);
+    });
+    const waitBackpressure = () => {
+        if ((channel.bufferedAmount ?? 0) <= high)
+            return Promise.resolve();
+        logger.log('carrier.backpressure.wait', { bufferedAmount: channel.bufferedAmount ?? 0, highWaterMark: high, lowWaterMark: low });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { cleanup(); reject(new Error('DataChannel 背压等待超时')); }, timeoutMs);
+            const check = () => { if ((channel.bufferedAmount ?? 0) <= low) {
+                cleanup();
+                resolve();
+            } };
+            const cleanup = () => { clearTimeout(timer); channel.removeEventListener('bufferedamountlow', check); channel.removeEventListener('close', fail); };
+            const fail = () => { cleanup(); reject(new Error('DataChannel 已关闭')); };
+            channel.bufferedAmountLowThreshold = low;
+            channel.addEventListener('bufferedamountlow', check);
+            channel.addEventListener('close', fail);
+            check();
+        });
+    };
+    const sendPhysical = async (data) => {
+        await waitOpen();
+        if (state !== 'open')
+            throw new Error('Codingns4DSH DataChannel 尚未 ready');
+        await waitBackpressure();
+        channel.send(data);
+        logger.log('carrier.send', { bytes: data.byteLength, bufferedAmount: channel.bufferedAmount ?? 0 });
+    };
+    const sendLogical = async (data) => {
+        if (data.byteLength <= DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES) {
+            await sendPhysical(data);
+            return;
+        }
+        const chunkCount = Math.ceil(data.byteLength / DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES);
+        const fragmentId = nextFragmentId = (nextFragmentId + 1) >>> 0;
+        logger.log('carrier.fragment.send', { fragmentId, chunkCount, totalBytes: data.byteLength, payloadBytes: DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES });
+        for (let index = 0; index < chunkCount; index += 1) {
+            const start = index * DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES;
+            const chunk = data.subarray(start, Math.min(data.byteLength, start + DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES));
+            await sendPhysical(encodeFragment(fragmentId, index, chunkCount, data.byteLength, chunk));
+        }
+    };
+    const acceptFragment = (data) => {
+        if (!isFragment(data))
+            return data;
+        const parsed = decodeFragment(data, maxReassemblyBytes);
+        let assembly = fragments.get(parsed.fragmentId);
+        if (!assembly) {
+            const timer = setTimeout(() => fragments.delete(parsed.fragmentId), reassemblyTimeoutMs);
+            assembly = { totalBytes: parsed.totalBytes, chunkCount: parsed.chunkCount, chunks: new Map(), receivedBytes: 0, timer };
+            fragments.set(parsed.fragmentId, assembly);
+            logger.log('carrier.fragment.receive', { fragmentId: parsed.fragmentId, chunkCount: parsed.chunkCount, totalBytes: parsed.totalBytes });
+        }
+        if (assembly.totalBytes !== parsed.totalBytes || assembly.chunkCount !== parsed.chunkCount)
+            throw new Error('DataChannel 分片元数据不一致');
+        if (assembly.chunks.has(parsed.index))
+            return null;
+        assembly.chunks.set(parsed.index, parsed.body);
+        assembly.receivedBytes += parsed.body.byteLength;
+        if (assembly.chunks.size !== assembly.chunkCount)
+            return null;
+        clearTimeout(assembly.timer);
+        fragments.delete(parsed.fragmentId);
+        const result = new Uint8Array(assembly.totalBytes);
+        let offset = 0;
+        for (let index = 0; index < assembly.chunkCount; index += 1) {
+            const chunk = assembly.chunks.get(index);
+            if (!chunk)
+                throw new Error('DataChannel 分片缺失');
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        if (offset !== assembly.totalBytes)
+            throw new Error('DataChannel 分片总长度不一致');
+        logger.log('carrier.fragment.complete', { fragmentId: parsed.fragmentId, chunks: assembly.chunkCount, totalBytes: result.byteLength });
+        return result;
+    };
+    return {
+        get state() { return state; },
+        send(data) {
+            if (!(data instanceof Uint8Array))
+                return Promise.reject(new TypeError('Carrier 只接受 Uint8Array'));
+            chain = chain.then(() => sendLogical(data));
+            return chain;
+        },
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        onClosed(listener) { if (closeNotified) {
+            listener('DataChannel closed');
+            return () => undefined;
+        } closeListeners.add(listener); return () => closeListeners.delete(listener); },
+        async close(reason) { if (state === 'closed')
+            return; state = 'closed'; clearFragments(); notifyClosed(reason ?? 'DataChannel closed'); channel.close(); channel.removeEventListener('open', onOpen); channel.removeEventListener('close', onClose); channel.removeEventListener('message', onMessage); listeners.clear(); },
+    };
+}
+function isFragment(data) {
+    return data.byteLength >= DATA_CHANNEL_FRAGMENT_HEADER_BYTES
+        && DATA_CHANNEL_FRAGMENT_MAGIC.every((value, index) => data[index] === value);
+}
+function encodeFragment(fragmentId, index, chunkCount, totalBytes, body) {
+    const result = new Uint8Array(DATA_CHANNEL_FRAGMENT_HEADER_BYTES + body.byteLength);
+    result.set(DATA_CHANNEL_FRAGMENT_MAGIC);
+    const view = new DataView(result.buffer);
+    view.setUint32(4, fragmentId);
+    view.setUint32(8, index);
+    view.setUint32(12, chunkCount);
+    view.setUint32(16, totalBytes);
+    result.set(body, DATA_CHANNEL_FRAGMENT_HEADER_BYTES);
+    return result;
+}
+function decodeFragment(data, maxReassemblyBytes) {
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const fragmentId = view.getUint32(4);
+    const index = view.getUint32(8);
+    const chunkCount = view.getUint32(12);
+    const totalBytes = view.getUint32(16);
+    if (chunkCount === 0 || totalBytes <= DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES || totalBytes > maxReassemblyBytes || index >= chunkCount)
+        throw new Error('DataChannel 分片头无效');
+    const expectedCount = Math.ceil(totalBytes / DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES);
+    if (chunkCount !== expectedCount)
+        throw new Error('DataChannel 分片数量无效');
+    const offset = index * DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES;
+    const expectedBytes = Math.min(DATA_CHANNEL_FRAGMENT_PAYLOAD_BYTES, totalBytes - offset);
+    const body = data.subarray(DATA_CHANNEL_FRAGMENT_HEADER_BYTES);
+    if (body.byteLength !== expectedBytes)
+        throw new Error('DataChannel 分片长度无效');
+    return { fragmentId, index, chunkCount, totalBytes, body: body.slice() };
+}
+function toBytes(value) {
+    if (value instanceof Uint8Array)
+        return new Uint8Array(value);
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value.slice(0));
+    if (ArrayBuffer.isView(value))
+        return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+    if (typeof Blob !== 'undefined' && value instanceof Blob)
+        return value.arrayBuffer().then((body) => new Uint8Array(body));
+    return null;
+}
+function bytesToHex(value) {
+    return [...value].map((item) => item.toString(16).padStart(2, '0')).join('');
+}
+//# sourceMappingURL=carrier.js.map

package/data/build/dist/transport/debug.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DSH Tunnel 调试日志。
+ *
+ * 日志只接受调用方明确传入的协议元数据，禁止把 Envelope body、票据、Cookie
+ * 或本地 Web 响应正文交给这个模块。默认关闭，生产环境不会产生额外输出。
+ */
+export type DshTransportDebugSide = 'h5' | 'host' | 'relay' | 'unknown';
+export interface DshTransportDebugLogger {
+    readonly enabled: boolean;
+    log(event: string, fields?: Readonly<Record<string, unknown>>): void;
+}
+export interface DshTransportDebugOptions {
+    readonly enabled?: boolean;
+    readonly side?: DshTransportDebugSide;
+    readonly component?: string;
+    readonly sink?: (record: Readonly<Record<string, unknown>>) => void;
+}
+/** 创建一个可注入测试 sink 的调试 logger。默认开关由当前运行环境决定。 */
+export declare function createDshTransportDebugLogger(options?: DshTransportDebugOptions): DshTransportDebugLogger;
+/** 解析 Host 环境变量、H5 URL/localStorage 和调试全局变量。 */
+export declare function resolveDshTransportDebugEnabled(): boolean;
+//# sourceMappingURL=debug.d.ts.map

package/data/build/dist/transport/debug.js

@@ -0,0 +1,57 @@
+const DEBUG_ENV = 'CODINGNS4DSH_TUNNEL_DEBUG';
+/** 创建一个可注入测试 sink 的调试 logger。默认开关由当前运行环境决定。 */
+export function createDshTransportDebugLogger(options = {}) {
+    const enabled = options.enabled ?? resolveDshTransportDebugEnabled();
+    const side = options.side ?? 'unknown';
+    const component = options.component ?? 'transport';
+    const sink = options.sink ?? ((record) => {
+        // console.info 在 Node 和浏览器中都能稳定显示，并且不会把正文拼进字符串。
+        console.info('[codingns4dsh:tunnel]', record);
+    });
+    return {
+        enabled,
+        log(event, fields = {}) {
+            if (!enabled)
+                return;
+            sink({
+                at: new Date().toISOString(),
+                side,
+                component,
+                event,
+                ...fields,
+            });
+        },
+    };
+}
+/** 解析 Host 环境变量、H5 URL/localStorage 和调试全局变量。 */
+export function resolveDshTransportDebugEnabled() {
+    const globalValue = globalThis.__CODINGNS4DSH_TUNNEL_DEBUG__;
+    if (globalValue !== undefined)
+        return parseDebugValue(globalValue);
+    if (typeof location !== 'undefined') {
+        const queryValue = new URL(location.href).searchParams.get('dshDebug');
+        if (queryValue !== null)
+            return parseDebugValue(queryValue);
+    }
+    if (typeof localStorage !== 'undefined') {
+        try {
+            const stored = localStorage.getItem('codingns4dsh-tunnel-debug');
+            if (stored !== null)
+                return parseDebugValue(stored);
+        }
+        catch {
+            // 隐私模式或受限 iframe 可能禁止读取 localStorage，继续检查其他来源。
+        }
+    }
+    if (typeof process !== 'undefined')
+        return parseDebugValue(process.env[DEBUG_ENV]);
+    return false;
+}
+function parseDebugValue(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value !== 'string')
+        return false;
+    return /^(1|true|yes|on)$/iu.test(value.trim());
+}
+//# sourceMappingURL=debug.js.map

package/data/build/dist/transport/dsh-envelope.d.ts

@@ -0,0 +1,41 @@
+/** DSH 多路复用层使用的 Host 作用域。 */
+export interface DshHostScope {
+    hostId: string;
+    hostLabel?: string;
+    workspaceId?: string;
+    sessionId?: string;
+    kind: 'local' | 'remote';
+}
+export type DshChannel = 'session' | 'rpc' | 'adapter' | 'pty' | 'task' | 'file' | 'port' | 'peerhost' | 'plugin' | 'web';
+export interface DshEnvelopeFlags {
+    endOfStream?: boolean;
+    cancelled?: boolean;
+    binary?: boolean;
+}
+/** DSH 业务层的统一消息格式。body 永远是原始二进制，不在这里做 Base64。 */
+export interface DshEnvelope {
+    version: 1;
+    messageId: string;
+    streamId: string;
+    channel: DshChannel;
+    type: string;
+    sequence: number;
+    generation: string;
+    hostScope: DshHostScope;
+    flags?: DshEnvelopeFlags;
+    meta: Record<string, unknown>;
+    body?: Uint8Array;
+}
+export interface DshEnvelopeCodecOptions {
+    maxBytes?: number;
+    maxMetaBytes?: number;
+}
+export declare const DSH_ENVELOPE_VERSION: 1;
+export declare const DSH_ENVELOPE_PROTOCOL = "dsh-transport-v1";
+export declare const DEFAULT_MAX_DSH_ENVELOPE_BYTES: number;
+export declare const DEFAULT_MAX_DSH_META_BYTES: number;
+/** 编码为 `DSH1 | 4 字节 JSON 头长度 | JSON 头 | 原始 body`。 */
+export declare function encodeDshEnvelope(envelope: DshEnvelope, options?: DshEnvelopeCodecOptions): Uint8Array;
+export declare function decodeDshEnvelope(data: Uint8Array, options?: DshEnvelopeCodecOptions): DshEnvelope;
+export declare function validateDshEnvelope(value: unknown): asserts value is DshEnvelope;
+//# sourceMappingURL=dsh-envelope.d.ts.map

package/data/build/dist/transport/dsh-envelope.js

@@ -0,0 +1,107 @@
+export const DSH_ENVELOPE_VERSION = 1;
+export const DSH_ENVELOPE_PROTOCOL = 'dsh-transport-v1';
+// Web 插件聚合 bundle 可能达到数 MiB；物理 DataChannel 已负责 64 KiB 分片，
+// Envelope 层只限制单条逻辑消息，和 Host 资源上限保持 16 MiB 一致。
+export const DEFAULT_MAX_DSH_ENVELOPE_BYTES = 16 * 1024 * 1024;
+export const DEFAULT_MAX_DSH_META_BYTES = 64 * 1024;
+const MAGIC = new Uint8Array([0x44, 0x53, 0x48, 0x01]);
+const channels = new Set(['session', 'rpc', 'adapter', 'pty', 'task', 'file', 'port', 'peerhost', 'plugin', 'web']);
+/** 编码为 `DSH1 | 4 字节 JSON 头长度 | JSON 头 | 原始 body`。 */
+export function encodeDshEnvelope(envelope, options = {}) {
+    validateDshEnvelope(envelope);
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_DSH_ENVELOPE_BYTES;
+    const maxMetaBytes = options.maxMetaBytes ?? DEFAULT_MAX_DSH_META_BYTES;
+    validateLimit(maxBytes, 'Envelope');
+    validateLimit(maxMetaBytes, 'Envelope meta');
+    const body = envelope.body ?? new Uint8Array();
+    const header = { ...envelope, bodyLength: body.byteLength };
+    delete header.body;
+    const headerBytes = new TextEncoder().encode(JSON.stringify(header));
+    if (headerBytes.byteLength > maxMetaBytes)
+        throw new Error('DSH Envelope meta 超过大小限制');
+    const result = new Uint8Array(MAGIC.byteLength + 4 + headerBytes.byteLength + body.byteLength);
+    result.set(MAGIC, 0);
+    new DataView(result.buffer).setUint32(MAGIC.byteLength, headerBytes.byteLength);
+    result.set(headerBytes, MAGIC.byteLength + 4);
+    result.set(body, MAGIC.byteLength + 4 + headerBytes.byteLength);
+    if (result.byteLength > maxBytes)
+        throw new Error('DSH Envelope 超过大小限制');
+    return result;
+}
+export function decodeDshEnvelope(data, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_DSH_ENVELOPE_BYTES;
+    const maxMetaBytes = options.maxMetaBytes ?? DEFAULT_MAX_DSH_META_BYTES;
+    validateLimit(maxBytes, 'Envelope');
+    validateLimit(maxMetaBytes, 'Envelope meta');
+    if (!(data instanceof Uint8Array))
+        throw new Error('DSH Envelope 必须是 Uint8Array');
+    if (data.byteLength > maxBytes)
+        throw new Error('DSH Envelope 超过大小限制');
+    if (data.byteLength < MAGIC.byteLength + 4 || !MAGIC.every((value, index) => data[index] === value)) {
+        throw new Error('DSH Envelope magic 无效');
+    }
+    const headerLength = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(MAGIC.byteLength);
+    if (headerLength > maxMetaBytes || MAGIC.byteLength + 4 + headerLength > data.byteLength) {
+        throw new Error('DSH Envelope 头部长度无效');
+    }
+    let header;
+    try {
+        header = JSON.parse(new TextDecoder().decode(data.subarray(MAGIC.byteLength + 4, MAGIC.byteLength + 4 + headerLength)));
+    }
+    catch (error) {
+        throw new Error('DSH Envelope 头部不是有效 JSON', { cause: error });
+    }
+    if (!header || typeof header !== 'object')
+        throw new Error('DSH Envelope 头部无效');
+    const value = header;
+    const bodyLength = value.bodyLength;
+    if (typeof bodyLength !== 'number' || !Number.isSafeInteger(bodyLength) || bodyLength < 0 || MAGIC.byteLength + 4 + headerLength + bodyLength !== data.byteLength) {
+        throw new Error('DSH Envelope body 长度无效');
+    }
+    delete value.bodyLength;
+    validateDshEnvelope(value);
+    const body = data.subarray(MAGIC.byteLength + 4 + headerLength);
+    return body.byteLength === 0 ? value : { ...value, body: body.slice() };
+}
+export function validateDshEnvelope(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('DSH Envelope 必须是对象');
+    const envelope = value;
+    if (envelope.version !== DSH_ENVELOPE_VERSION)
+        throw new Error('DSH Envelope 版本不兼容');
+    if (typeof envelope.messageId !== 'string' || envelope.messageId.length === 0)
+        throw new Error('DSH Envelope messageId 无效');
+    if (typeof envelope.streamId !== 'string' || envelope.streamId.length === 0)
+        throw new Error('DSH Envelope streamId 无效');
+    if (!channels.has(envelope.channel))
+        throw new Error('DSH Envelope channel 无效');
+    if (typeof envelope.type !== 'string' || envelope.type.length === 0)
+        throw new Error('DSH Envelope type 无效');
+    if (!Number.isSafeInteger(envelope.sequence) || envelope.sequence < 0)
+        throw new Error('DSH Envelope sequence 无效');
+    if (typeof envelope.generation !== 'string' || envelope.generation.length === 0)
+        throw new Error('DSH Envelope generation 无效');
+    validateHostScope(envelope.hostScope);
+    if (!envelope.meta || typeof envelope.meta !== 'object' || Array.isArray(envelope.meta))
+        throw new Error('DSH Envelope meta 无效');
+    if (envelope.body !== undefined && !(envelope.body instanceof Uint8Array))
+        throw new Error('DSH Envelope body 必须是 Uint8Array');
+}
+function validateHostScope(scope) {
+    if (!scope || typeof scope !== 'object')
+        throw new Error('DSH Envelope hostScope 无效');
+    const value = scope;
+    if (typeof value.hostId !== 'string' || value.hostId.length === 0)
+        throw new Error('DSH Envelope hostScope.hostId 无效');
+    if (value.kind !== 'local' && value.kind !== 'remote')
+        throw new Error('DSH Envelope hostScope.kind 无效');
+    for (const key of ['hostLabel', 'workspaceId', 'sessionId']) {
+        if (value[key] !== undefined && typeof value[key] !== 'string')
+            throw new Error(`DSH Envelope hostScope.${key} 无效`);
+    }
+}
+function validateLimit(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${name} 大小限制无效`);
+}
+//# sourceMappingURL=dsh-envelope.js.map

package/data/build/dist/transport/dsh-gateway.d.ts

@@ -0,0 +1,64 @@
+import type { CodingNsCarrier } from './carrier.js';
+import { type DshChannel, type DshEnvelope, type DshHostScope } from './dsh-envelope.js';
+import { DshSession, type DshSessionOptions } from './dsh-session.js';
+import { type DshTransportDebugLogger } from './debug.js';
+export declare const DSH_GATEWAY_PATH = "/__dsh__/transport/v1";
+export interface DshStreamContext {
+    readonly envelope: DshEnvelope;
+    readonly session: DshSession;
+    send(type: string, meta?: Record<string, unknown>, body?: Uint8Array): void;
+    close(): void;
+}
+export interface DshGatewayFeature {
+    readonly channel?: DshChannel;
+    readonly operation?: string;
+    canHandle?(envelope: DshEnvelope): boolean | Promise<boolean>;
+    handleStream?(context: DshStreamContext): void | Promise<void> | AsyncIterable<DshEnvelope>;
+    handleMessage?(context: DshStreamContext, envelope: DshEnvelope): void | Promise<void>;
+    handleWindow?(context: DshStreamContext, envelope: DshEnvelope): void | Promise<void>;
+}
+export interface DshGatewayOptions {
+    carrier: CodingNsCarrier;
+    session?: DshSession;
+    sessionOptions?: Omit<DshSessionOptions, 'carrier'>;
+    /** 只依赖 FeatureRegistry 的 modules()，避免把具体 Host services 类型泄漏到传输层。 */
+    registry?: {
+        modules(): readonly unknown[];
+    };
+    features?: readonly DshGatewayFeature[];
+    hostScope: DshHostScope;
+    generation: string;
+    /** 当前 DSH 宿主版本；用于没有显式 session 的默认 Gateway。 */
+    dshVersion?: string;
+    maxStreams?: number;
+    debug?: DshTransportDebugLogger;
+}
+/** 将 DSH Session 后的 Envelope 按 streamId 路由到 FeatureRegistry 模块。 */
+export declare class DshGateway {
+    private readonly options;
+    readonly session: DshSession;
+    private readonly streams;
+    /**
+     * stream.open 的 feature 选择和本地资源创建可能异步完成。
+     * 取消帧可以在这段窗口内到达，必须先登记 opening，不能让取消穿透后又把旧流插入 streams。
+     */
+    private readonly opening;
+    private readonly cancelledOpening;
+    private readonly maxStreams;
+    private readonly features;
+    private sequence;
+    private started;
+    private unsubscribe;
+    private readonly debug;
+    constructor(options: DshGatewayOptions);
+    start(): void;
+    close(reason?: string): Promise<void>;
+    get path(): string;
+    private route;
+    private openStream;
+    private findFeature;
+    private sendError;
+    private send;
+    private nextSequence;
+}
+//# sourceMappingURL=dsh-gateway.d.ts.map