@deepseek-harness-tui/dsh-tui 0.10.0 → 0.10.2

package/lib/types/adapter/channel/host-registry.js

@@ -0,0 +1,120 @@
+/**
+ * Host-internal Channel registry for the adapter Kernel.
+ *
+ * The live `Channel` is created by the TUI plugin row after the plugin-host
+ * Kernel may already have been constructed/mounted. Rather than trying to
+ * reorder service mounting, the TUI stores the live Channel under its
+ * composition root in a WeakMap; the Channel driver resolves it lazily when
+ * a Port method is actually called. This keeps the Kernel's composition
+ * independent of the TUI render lifecycle.
+ *
+ * Every entry is normalized to the Cordis composition root before it is used
+ * as a WeakMap key: a child/plugin context passed by a caller must never
+ * create a registry entry that the Kernel (which queries through the root)
+ * cannot resolve.
+ */
+import { compositionRoot } from '../../dsh-adapter/host-access.js';
+const channels = new WeakMap();
+const channelListeners = new WeakMap();
+const registrationListeners = new WeakMap();
+function rootKey(ctx) {
+    if (ctx === null || (typeof ctx !== 'object' && typeof ctx !== 'function'))
+        return undefined;
+    try {
+        return compositionRoot(ctx);
+    }
+    catch {
+        // Non-Cordis test values / minimal embedders are their own root.
+        return ctx;
+    }
+}
+/** Register the live Channel for a composition root.
+ * @returns A token-safe disposer. Registrations have identity independent of
+ * their Channel object: A → B → A and repeated registration of the same
+ * Channel cannot let an older disposer erase or revive the current entry.
+ */
+export function registerTuiChannel(ctx, channel) {
+    const key = rootKey(ctx);
+    if (key === undefined)
+        return () => false;
+    const registration = Object.freeze({ channel, token: Symbol('tui-channel-registration') });
+    channels.set(key, registration);
+    notifyChannelListeners(key, registration);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return false;
+        disposed = true;
+        if (channels.get(key)?.token !== registration.token)
+            return false;
+        channels.delete(key);
+        notifyChannelListeners(key, undefined);
+        return true;
+    };
+}
+function notifyChannelListeners(key, registration) {
+    const listeners = channelListeners.get(key);
+    if (listeners !== undefined) {
+        for (const listener of [...listeners]) {
+            try {
+                listener(registration?.channel);
+            }
+            catch {
+                // A registration notification is advisory; one faulty listener must not
+                // prevent the Channel from being stored.
+            }
+        }
+    }
+    const identityListeners = registrationListeners.get(key);
+    if (identityListeners === undefined)
+        return;
+    for (const listener of [...identityListeners]) {
+        try {
+            listener(registration);
+        }
+        catch {
+            // Identity notifications have the same advisory, fan-out semantics.
+        }
+    }
+}
+/** Resolve the live Channel for a composition root. */
+export function getRegisteredTuiChannel(ctx) {
+    return getTuiChannelRegistration(ctx)?.channel;
+}
+/** Return the current registration identity, not only its Channel object. */
+export function getTuiChannelRegistration(ctx) {
+    const key = rootKey(ctx);
+    return key === undefined ? undefined : channels.get(key);
+}
+/**
+ * Subscribe to live-Channel registration for one composition root.
+ *
+ * The Kernel uses this to re-run a refresh/mount when the TUI plugin creates
+ * and registers its Channel after the plugin-host row has already started.
+ * Returns a disposer; listeners are keyed by normalized composition root.
+ */
+export function onTuiChannelRegistered(ctx, listener) {
+    const key = rootKey(ctx);
+    if (key === undefined)
+        return () => undefined;
+    let listeners = channelListeners.get(key);
+    if (listeners === undefined) {
+        listeners = new Set();
+        channelListeners.set(key, listeners);
+    }
+    listeners.add(listener);
+    return () => { listeners?.delete(listener); };
+}
+/** Subscribe to registration identities for consumers that own capabilities. */
+export function onTuiChannelRegistration(ctx, listener) {
+    const key = rootKey(ctx);
+    if (key === undefined)
+        return () => undefined;
+    let listeners = registrationListeners.get(key);
+    if (listeners === undefined) {
+        listeners = new Set();
+        registrationListeners.set(key, listeners);
+    }
+    listeners.add(listener);
+    return () => { listeners?.delete(listener); };
+}

package/lib/types/adapter/channel/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Channel split surface (P4).
+ *
+ * The live legacy `src/dsh-adapter/channel.ts` remains the implementation
+ * source, but the adapter-facing Channel behavior is decomposed here into
+ * five small modules:
+ *   projection / actions / state / plugins / transcript.
+ *
+ * This module re-exports the host-internal builder functions and the
+ * composition-root registry.
+ */
+export { projectChannelRows, projectChannelSnapshot } from './projection.js';
+export { projectChannelState } from './state.js';
+export { createChannelActions } from './actions.js';
+export { createChannelPlugins } from './plugins.js';
+export { createChannelTranscript } from './transcript.js';
+export { registerTuiChannel, onTuiChannelRegistered } from './host-registry.js';
+export { CHANNEL_FEATURES, CHANNEL_PORT_METHOD_CAPABILITIES, CHANNEL_STANDARD_DECLARATIONS } from './features.js';
+export { TUI_CHANNEL_WIRE_REVISION, type TuiChannelSnapshot } from '../spec/index.js';
+export { createReplayChannelProvider, createReplayChannelProviderFromSnapshot, REPLAY_CHANNEL_WIRE_REVISION, type ChannelProvider, type ChannelProviderOpenInput, type ReplayChannelSnapshotSource, } from './provider.js';
+export { createChannelConsumer, type ChannelConsumer, } from './consumer.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/adapter/channel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapter/channel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC/E,OAAO,EAAE,gBAAgB,EAAE,gCAAgC,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAA;AACjH,OAAO,EAAE,yBAAyB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrF,OAAO,EACL,2BAA2B,EAC3B,uCAAuC,EACvC,4BAA4B,EAC5B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,GACjC,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAA"}

package/lib/types/adapter/channel/index.js

@@ -0,0 +1,21 @@
+/**
+ * Channel split surface (P4).
+ *
+ * The live legacy `src/dsh-adapter/channel.ts` remains the implementation
+ * source, but the adapter-facing Channel behavior is decomposed here into
+ * five small modules:
+ *   projection / actions / state / plugins / transcript.
+ *
+ * This module re-exports the host-internal builder functions and the
+ * composition-root registry.
+ */
+export { projectChannelRows, projectChannelSnapshot } from './projection.js';
+export { projectChannelState } from './state.js';
+export { createChannelActions } from './actions.js';
+export { createChannelPlugins } from './plugins.js';
+export { createChannelTranscript } from './transcript.js';
+export { registerTuiChannel, onTuiChannelRegistered } from './host-registry.js';
+export { CHANNEL_FEATURES, CHANNEL_PORT_METHOD_CAPABILITIES, CHANNEL_STANDARD_DECLARATIONS } from './features.js';
+export { TUI_CHANNEL_WIRE_REVISION } from '../spec/index.js';
+export { createReplayChannelProvider, createReplayChannelProviderFromSnapshot, REPLAY_CHANNEL_WIRE_REVISION, } from './provider.js';
+export { createChannelConsumer, } from './consumer.js';

package/lib/types/adapter/channel/internal-token.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal capability token for the split Channel builder modules.
+ *
+ * The split `actions` / `plugins` / `transcript` builders are host-internal
+ * and must be reached through the Kernel-driven Channel driver / HostFacade
+ * shadow gate, not imported and invoked directly from arbitrary TUI code.
+ * This token is intentionally not re-exported through `src/adapter/channel`
+ * or `src/adapter/index`; only the upstream driver and the split modules
+ * themselves import it.
+ */
+export declare const CHANNEL_SPLIT_TOKEN: unique symbol;
+//# sourceMappingURL=internal-token.d.ts.map

package/lib/types/adapter/channel/internal-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-token.d.ts","sourceRoot":"","sources":["../../../../src/adapter/channel/internal-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA8C,CAAA"}

package/lib/types/adapter/channel/internal-token.js

@@ -0,0 +1,11 @@
+/**
+ * Internal capability token for the split Channel builder modules.
+ *
+ * The split `actions` / `plugins` / `transcript` builders are host-internal
+ * and must be reached through the Kernel-driven Channel driver / HostFacade
+ * shadow gate, not imported and invoked directly from arbitrary TUI code.
+ * This token is intentionally not re-exported through `src/adapter/channel`
+ * or `src/adapter/index`; only the upstream driver and the split modules
+ * themselves import it.
+ */
+export const CHANNEL_SPLIT_TOKEN = Symbol('dsh-tui.channel-split-token');

package/lib/types/adapter/channel/plugins.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Channel plugins module (P4 channel split).
+ *
+ * Projects the plugin-visible seams that hang off the live Channel into a
+ * small host-internal Port: external plugin commands, plugin scenes and
+ * settings sections. It never exposes plugin registration or permission
+ * evaluation; those stay in Standard/Kernel.
+ *
+ * The internal `CHANNEL_SPLIT_TOKEN` is required so this split builder cannot
+ * be invoked outside the Kernel/driver path and bypass the HostFacade shadow
+ * gate.
+ */
+import type { Channel } from '../../dsh-adapter/channel.js';
+import type { HostChannelPluginsPort } from '../ports/channel.js';
+/** Build the host-internal plugin-facing surface over one live Channel. */
+export declare function createChannelPlugins(channel: Channel, token: symbol): HostChannelPluginsPort;
+//# sourceMappingURL=plugins.d.ts.map

package/lib/types/adapter/channel/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../../src/adapter/channel/plugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAA;AAE3D,OAAO,KAAK,EACV,sBAAsB,EAEvB,MAAM,qBAAqB,CAAA;AAuB5B,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAa5F"}

package/lib/types/adapter/channel/plugins.js

@@ -0,0 +1,47 @@
+/**
+ * Channel plugins module (P4 channel split).
+ *
+ * Projects the plugin-visible seams that hang off the live Channel into a
+ * small host-internal Port: external plugin commands, plugin scenes and
+ * settings sections. It never exposes plugin registration or permission
+ * evaluation; those stay in Standard/Kernel.
+ *
+ * The internal `CHANNEL_SPLIT_TOKEN` is required so this split builder cannot
+ * be invoked outside the Kernel/driver path and bypass the HostFacade shadow
+ * gate.
+ */
+import { CHANNEL_SPLIT_TOKEN } from './internal-token.js';
+function projectSettingsSection(section) {
+    return Object.freeze({
+        ns: section.ns,
+        title: section.title,
+        ...(section.groups === undefined ? {} : {
+            groups: Object.freeze(section.groups.map(group => Object.freeze({ id: group.id, title: group.title }))),
+        }),
+        fields: Object.freeze(section.fields.map(field => Object.freeze({
+            path: Object.freeze([...field.path]),
+            label: field.label,
+            kind: field.kind,
+            ...(field.hint === undefined ? {} : { hint: field.hint }),
+            ...(field.group === undefined ? {} : { group: field.group }),
+            ...(field.options === undefined ? {} : { options: Object.freeze(field.options.map(option => Object.freeze({ ...option }))) }),
+            ...(field.placeholder === undefined ? {} : { placeholder: field.placeholder }),
+            ...(field.secret === undefined ? {} : { secret: Object.freeze({ ref: field.secret.ref }) }),
+        }))),
+    });
+}
+/** Build the host-internal plugin-facing surface over one live Channel. */
+export function createChannelPlugins(channel, token) {
+    if (token !== CHANNEL_SPLIT_TOKEN) {
+        throw new Error('dsh-tui: Channel split plugins require the internal host token');
+    }
+    return Object.freeze({
+        async runExternalCommand(name, rawInput) {
+            return channel.runExternalCommand(name, rawInput);
+        },
+        openPluginScene: id => channel.openPluginScene(id),
+        closePluginScene: () => channel.closePluginScene(),
+        settingsSections: () => Object.freeze(channel.settingsSections().map(projectSettingsSection)),
+        subscribeSettingsSections: listener => channel.subscribeSettingsSections(listener),
+    });
+}

package/lib/types/adapter/channel/projection.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Channel projection module (P4 channel split).
+ *
+ * This is the pure projection half of the live Channel: it maps the legacy
+ * Channel/ChannelState surface into a serializable host-internal projection
+ * used by the Kernel Channel Port. It deliberately strips functions, handles,
+ * secrets and renderer-only objects from the snapshot.
+ */
+import type { Channel, ChatRow } from '../../dsh-adapter/channel.js';
+import type { HostChannelProjectionSnapshot, HostChannelRowProjection } from '../ports/channel.js';
+/** Project the current channel transcript rows into a JSON-safe view. */
+export declare function projectChannelRows(rows: readonly ChatRow[]): readonly HostChannelRowProjection[];
+/** Project the live Channel into the serializable renderer projection. */
+export declare function projectChannelSnapshot(channel: Channel): HostChannelProjectionSnapshot;
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/adapter/channel/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../src/adapter/channel/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAW,MAAM,8BAA8B,CAAA;AAC7E,OAAO,KAAK,EACV,6BAA6B,EAC7B,wBAAwB,EAEzB,MAAM,qBAAqB,CAAA;AA4B5B,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,wBAAwB,EAAE,CAEhG;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,6BAA6B,CAqBtF"}

package/lib/types/adapter/channel/projection.js

@@ -0,0 +1,59 @@
+/**
+ * Channel projection module (P4 channel split).
+ *
+ * This is the pure projection half of the live Channel: it maps the legacy
+ * Channel/ChannelState surface into a serializable host-internal projection
+ * used by the Kernel Channel Port. It deliberately strips functions, handles,
+ * secrets and renderer-only objects from the snapshot.
+ */
+function projectTool(row) {
+    return Object.freeze({
+        callId: row.callId,
+        name: row.name,
+        status: row.status,
+        argsPreview: row.argsText,
+        ...(row.resultText === undefined ? {} : { resultPreview: row.resultText }),
+        ...(row.errorText === undefined ? {} : { errorText: row.errorText }),
+        startedAt: row.startedAt,
+        ...(row.durationMs === undefined ? {} : { durationMs: row.durationMs }),
+    });
+}
+function projectRow(row) {
+    return Object.freeze({
+        id: row.id,
+        kind: row.kind,
+        text: row.text,
+        ...(row.label === undefined ? {} : { label: row.label }),
+        ...(row.streaming === undefined ? {} : { streaming: row.streaming }),
+        ...(row.time === undefined ? {} : { time: row.time }),
+        ...(row.seq === undefined ? {} : { seq: row.seq }),
+        ...(row.tool === undefined ? {} : { tool: projectTool(row.tool) }),
+    });
+}
+/** Project the current channel transcript rows into a JSON-safe view. */
+export function projectChannelRows(rows) {
+    return Object.freeze(rows.map(projectRow));
+}
+/** Project the live Channel into the serializable renderer projection. */
+export function projectChannelSnapshot(channel) {
+    return Object.freeze({
+        version: channel.version,
+        rows: projectChannelRows(channel.rows),
+        status: channel.status,
+        sessionTitle: channel.sessionTitle,
+        agentId: channel.agentId,
+        model: channel.model,
+        provider: channel.provider,
+        cwd: channel.cwd,
+        displayCwd: channel.displayCwd,
+        working: channel.working,
+        activeToolCount: channel.activeToolCount,
+        lastUserText: channel.lastUserText,
+        commandList: Object.freeze(channel.commandList.map(command => Object.freeze({
+            name: command.name,
+            ...(command.description === undefined ? {} : { description: command.description }),
+        }))),
+        contextSegments: Object.freeze({ ...channel.contextSegments }),
+        subagents: Object.freeze([...channel.subagents]),
+    });
+}

package/lib/types/adapter/channel/provider.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TUI Channel Provider (P5).
+ *
+ * A Channel Provider owns the Agent/Session/Workspace side of
+ * `tui.dsh/v1alpha1#Channel`. This module implements an in-memory replay
+ * provider used by the replay harness: it does not attach to a real DSH
+ * service, but it follows the protocol envelope (open/subscribe/invoke/
+ * close), validates inputs/outputs, preserves monotonic channel versions,
+ * and can be driven from a real recorded DSH session snapshot/transcript.
+ *
+ * The replay provider is intentionally protocol-envelope focused:
+ * - unknown methods are rejected (never treated as a successful no-op);
+ * - feature/support validation happens in the replay harness, not here;
+ * - values are bounded in size/depth and deep-frozen before being handed out;
+ * - method handlers only run inside the harness-provided replay isolation.
+ */
+import type { TuiChannelInvokeOutput, TuiChannelSnapshot } from '../spec/index.js';
+export interface ChannelProviderOpenInput {
+    readonly workspace?: string;
+    readonly sessionId?: string;
+    readonly options?: unknown;
+}
+export interface ChannelProvider {
+    open(input: ChannelProviderOpenInput): Promise<TuiChannelSnapshot>;
+    subscribe(channelId: string, afterVersion: number, listener: (snapshot: TuiChannelSnapshot) => void): Promise<() => void>;
+    invoke(channelId: string, method: string, args: readonly unknown[]): Promise<TuiChannelInvokeOutput>;
+    close(channelId: string): Promise<{
+        readonly closed: true;
+    }>;
+}
+export interface ReplayChannelSnapshotSource {
+    /** Monotonic snapshots, oldest first. The provider serves the latest
+     * snapshot from `open` and replays newer snapshots through `subscribe`. */
+    readonly snapshots: readonly TuiChannelSnapshot[];
+    /** Optional transcript/event log carried alongside the snapshots. It is
+     * not interpreted by the provider; it exists for replay provenance and
+     * for conformance report details. */
+    readonly transcript?: readonly unknown[];
+    /** Optional method invocation handlers. Unknown methods are rejected with
+     * `FEATURE_UNAVAILABLE` (or `INVALID_ARGUMENT` for malformed input). */
+    readonly methods?: Readonly<Record<string, (args: readonly unknown[]) => unknown | Promise<unknown>>>;
+}
+/** Safety bound for replay JSON payloads. */
+export declare const REPLAY_JSON_MAX_BYTES: number;
+/** Safety bound for replay JSON nesting depth. */
+export declare const REPLAY_JSON_MAX_DEPTH = 64;
+/** Create an isolated replay Channel Provider over recorded snapshots. */
+export declare function createReplayChannelProvider(source: ReplayChannelSnapshotSource): ChannelProvider;
+/** Convenience provider over one snapshot (common replay fixture). */
+export declare function createReplayChannelProviderFromSnapshot(snapshot: TuiChannelSnapshot, transcript?: readonly unknown[]): ChannelProvider;
+export declare const REPLAY_CHANNEL_WIRE_REVISION: 6;
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/adapter/channel/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/adapter/channel/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAElF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAClE,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,GAC/C,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAClC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED,MAAM,WAAW,2BAA2B;IAC1C;+EAC2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACjD;;yCAEqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACxC;4EACwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;CACtG;AAED,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,QAAa,CAAA;AAC/C,kDAAkD;AAClD,eAAO,MAAM,qBAAqB,KAAK,CAAA;AA2EvC,0EAA0E;AAC1E,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,2BAA2B,GAAG,eAAe,CA2HhG;AAED,sEAAsE;AACtE,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,GAAE,SAAS,OAAO,EAAO,GAClC,eAAe,CAKjB;AAUD,eAAO,MAAM,4BAA4B,GAA4B,CAAA"}

package/lib/types/adapter/channel/provider.js

@@ -0,0 +1,231 @@
+/**
+ * TUI Channel Provider (P5).
+ *
+ * A Channel Provider owns the Agent/Session/Workspace side of
+ * `tui.dsh/v1alpha1#Channel`. This module implements an in-memory replay
+ * provider used by the replay harness: it does not attach to a real DSH
+ * service, but it follows the protocol envelope (open/subscribe/invoke/
+ * close), validates inputs/outputs, preserves monotonic channel versions,
+ * and can be driven from a real recorded DSH session snapshot/transcript.
+ *
+ * The replay provider is intentionally protocol-envelope focused:
+ * - unknown methods are rejected (never treated as a successful no-op);
+ * - feature/support validation happens in the replay harness, not here;
+ * - values are bounded in size/depth and deep-frozen before being handed out;
+ * - method handlers only run inside the harness-provided replay isolation.
+ */
+import { TUI_CHANNEL_WIRE_REVISION, validateTuiChannelInput, validateTuiChannelOutput, validateTuiChannelSnapshot, } from '../spec/index.js';
+import { isReplayIsolationActive } from '../kernel/replay-isolation.js';
+/** Safety bound for replay JSON payloads. */
+export const REPLAY_JSON_MAX_BYTES = 512 * 1024;
+/** Safety bound for replay JSON nesting depth. */
+export const REPLAY_JSON_MAX_DEPTH = 64;
+function deepFreezeCopy(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const existing = seen.get(value);
+    if (existing !== undefined)
+        return existing;
+    if (Array.isArray(value)) {
+        const copy = [];
+        seen.set(value, copy);
+        for (const item of value)
+            copy.push(deepFreezeCopy(item, seen));
+        return Object.freeze(copy);
+    }
+    const copy = {};
+    seen.set(value, copy);
+    for (const [key, item] of Object.entries(value)) {
+        copy[key] = deepFreezeCopy(item, seen);
+    }
+    return Object.freeze(copy);
+}
+function assertBoundedJson(value, label, depth = 0, ancestors = new Set()) {
+    if (depth > REPLAY_JSON_MAX_DEPTH) {
+        throw new TypeError(`${label}: JSON nesting exceeds ${REPLAY_JSON_MAX_DEPTH} levels`);
+    }
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError(`${label}: JSON numbers must be finite`);
+        return;
+    }
+    if (typeof value !== 'object') {
+        throw new TypeError(`${label}: must be a JSON value`);
+    }
+    if (ancestors.has(value))
+        throw new TypeError(`${label}: must not contain cycles`);
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries())
+            assertBoundedJson(item, `${label}[${index}]`, depth + 1, ancestors);
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`${label}: must contain only plain objects`);
+        }
+        for (const [key, item] of Object.entries(value)) {
+            assertBoundedJson(item, `${label}.${key}`, depth + 1, ancestors);
+        }
+    }
+    ancestors.delete(value);
+}
+function assertJsonSize(value, label) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        throw new TypeError(`${label}: value is not JSON-serializable`);
+    }
+    if (json === undefined)
+        throw new TypeError(`${label}: value is not JSON-serializable`);
+    if (Buffer.byteLength(json, 'utf8') > REPLAY_JSON_MAX_BYTES) {
+        throw new TypeError(`${label}: JSON payload exceeds ${REPLAY_JSON_MAX_BYTES} bytes`);
+    }
+}
+function channelSnapshot(value) {
+    const validated = validateTuiChannelSnapshot(value);
+    assertBoundedJson(validated, 'Channel snapshot');
+    assertJsonSize(validated, 'Channel snapshot');
+    return deepFreezeCopy(validated);
+}
+function invokeOutput(value) {
+    const validated = validateTuiChannelOutput('invoke', value);
+    assertBoundedJson(validated, 'Channel invoke output');
+    assertJsonSize(validated, 'Channel invoke output');
+    return deepFreezeCopy(validated);
+}
+/** Create an isolated replay Channel Provider over recorded snapshots. */
+export function createReplayChannelProvider(source) {
+    if (!Array.isArray(source.snapshots) || source.snapshots.length === 0) {
+        throw new TypeError('replay Channel provider requires at least one snapshot');
+    }
+    if (source.methods !== undefined && (source.methods === null
+        || typeof source.methods !== 'object'
+        || (Object.getPrototypeOf(source.methods) !== Object.prototype && Object.getPrototypeOf(source.methods) !== null))) {
+        throw new TypeError('replay Channel methods must be a plain object map');
+    }
+    for (const [name, handler] of Object.entries(source.methods ?? {})) {
+        if (typeof handler !== 'function') {
+            throw new TypeError(`replay Channel method "${name}" must be a function`);
+        }
+    }
+    const snapshots = Object.freeze([...source.snapshots].map(channelSnapshot));
+    for (let index = 1; index < snapshots.length; index += 1) {
+        const previous = snapshots[index - 1];
+        const current = snapshots[index];
+        if (current.channelId !== previous.channelId) {
+            throw new TypeError('replay Channel snapshots must share one channelId');
+        }
+        if (!(current.version > previous.version)) {
+            throw new TypeError('replay Channel snapshots must have strictly increasing versions');
+        }
+    }
+    let currentIndex = snapshots.length - 1;
+    let closed = false;
+    function latest() {
+        return snapshots[currentIndex];
+    }
+    function assertOpen() {
+        if (closed)
+            throw new Error('CHANNEL_CLOSED');
+    }
+    return Object.freeze({
+        async open(input) {
+            validateTuiChannelInput('open', {
+                ...input,
+                ...(input.options === undefined ? {} : { options: input.options }),
+            });
+            // The replay provider is a deterministic fixture harness, not a DSH
+            // endpoint that resolves workspace/session authorities. Selector
+            // resolution is explicitly unsupported: silently returning the latest
+            // snapshot for a wrong selector would be a false conformance claim.
+            if ((input.workspace !== undefined && input.workspace !== '')
+                || (input.sessionId !== undefined && input.sessionId !== '')) {
+                throw new Error('REPLAY_PROVIDER_UNSUPPORTED_SELECTOR: replay provider does not resolve workspace/sessionId selectors');
+            }
+            closed = false;
+            return latest();
+        },
+        async subscribe(channelId, afterVersion, listener) {
+            validateTuiChannelInput('subscribe', { channelId, afterVersion });
+            assertOpen();
+            const channel = latest();
+            if (channel.channelId !== channelId) {
+                throw new Error('CHANNEL_NOT_FOUND');
+            }
+            let stopped = false;
+            // RFC: subscribe is "not earlier than afterVersion", so equal/version 0
+            // snapshots must also be delivered.
+            for (const snapshot of snapshots) {
+                if (stopped)
+                    break;
+                if (snapshot.version >= afterVersion) {
+                    listener(snapshot);
+                }
+            }
+            return () => {
+                stopped = true;
+            };
+        },
+        async invoke(channelId, method, args) {
+            validateTuiChannelInput('invoke', { channelId, method, arguments: args });
+            assertBoundedJson(args, 'Channel.invoke arguments');
+            assertJsonSize(args, 'Channel.invoke arguments');
+            assertOpen();
+            const channel = latest();
+            if (channel.channelId !== channelId) {
+                throw new Error('CHANNEL_NOT_FOUND');
+            }
+            const handler = source.methods !== undefined && Object.hasOwn(source.methods, method)
+                ? source.methods[method]
+                : undefined;
+            if (typeof handler !== 'function') {
+                // Unknown methods are protocol errors, never a successful no-op.
+                throw new Error(`FEATURE_UNAVAILABLE: unknown Channel method "${method}"`);
+            }
+            if (!isReplayIsolationActive()) {
+                throw new Error('replay Channel method handlers may only run inside replay isolation');
+            }
+            const value = await handler(args);
+            assertJsonValue(value);
+            const output = invokeOutput({
+                value: value ?? null,
+                valueDefined: value !== undefined,
+                ...({ snapshot: latest() }),
+            });
+            // The protocol's `invoke` output is validated above; if a provider
+            // advances state in the future, the snapshot returned must remain
+            // monotonic. The replay provider is intentionally read-only, so the
+            // snapshot never regresses.
+            return output;
+        },
+        async close(channelId) {
+            validateTuiChannelInput('close', { channelId });
+            const channel = latest();
+            if (channel.channelId !== channelId) {
+                throw new Error('CHANNEL_NOT_FOUND');
+            }
+            closed = true;
+            return { closed: true };
+        },
+    });
+}
+/** Convenience provider over one snapshot (common replay fixture). */
+export function createReplayChannelProviderFromSnapshot(snapshot, transcript = []) {
+    return createReplayChannelProvider({
+        snapshots: [snapshot],
+        transcript,
+    });
+}
+function assertJsonValue(value) {
+    if (typeof value === 'function' || typeof value === 'symbol') {
+        throw new TypeError('replay Channel values must be JSON-serializable');
+    }
+    assertBoundedJson(value, 'Channel.invoke result');
+    assertJsonSize(value, 'Channel.invoke result');
+}
+export const REPLAY_CHANNEL_WIRE_REVISION = TUI_CHANNEL_WIRE_REVISION;

package/lib/types/adapter/channel/read-view.d.ts

@@ -0,0 +1,4 @@
+/** Detached in-process read projections. Executable leaves are guarded, not serialized. */
+export declare function markChannelReadDirty(value: object): void;
+export declare function createChannelReadView(check: (mutation: boolean) => void): <T>(value: T, nextVersion: number) => T;
+//# sourceMappingURL=read-view.d.ts.map

package/lib/types/adapter/channel/read-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-view.d.ts","sourceRoot":"","sources":["../../../../src/adapter/channel/read-view.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAgB3F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAExD;AAQD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,IAgG9D,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,MAAM,KAAG,CAAC,CAI7C"}