@khorsheed/dsh-room 0.1.0

package/lib/types/client/nodes.js

@@ -0,0 +1,212 @@
+/** The shared final-node materialization (single shape across the three kinds). */
+function viewNode(context, kind, visibility = 'visible') {
+    if (context.state === undefined)
+        return null;
+    return {
+        key: context.key,
+        kind,
+        id: context.id,
+        target: 'chat',
+        anchorSeq: context.state.seq,
+        location: context.start?.location ?? { kind: 'unresolved' },
+        visibility,
+        data: context.state,
+    };
+}
+/**
+ * The member-speech Definition: one single-event Context per room/speech
+ * event (a CLI member's reply mirrored onto the blackboard).
+ */
+export const roomSpeechDefinition = {
+    kind: 'room-speech',
+    target: 'chat',
+    match: event => event.type === 'room/speech'
+        ? { id: String(event.seq), role: 'start' }
+        : null,
+    start: (_context, match) => {
+        const event = match.event;
+        if (event.type !== 'room/speech')
+            throw new Error('room-speech start requires a room/speech event');
+        return {
+            seq: event.seq,
+            time: event.time,
+            member: event.data.member,
+            text: event.data.text,
+            ...event.data.interrupted === undefined ? {} : { interrupted: event.data.interrupted },
+            ...event.data.childSessionId === undefined ? {} : { childSessionId: event.data.childSessionId },
+            ...event.data.durationMs === undefined ? {} : { durationMs: event.data.durationMs },
+        };
+    },
+    update: context => context.state,
+    buildViewNode: context => viewNode(context, 'room-speech'),
+};
+/**
+ * The member-run Definition: one Context per run (matched on
+ * member+startedAt), started by the running edge and updated by its terminal
+ * edge. A running run renders the live row; a failed run stays as a dim
+ * error row; done/cancelled hide the row IN PLACE — the assembler's live
+ * incremental flush forbids withdrawing a materialized node with null (the
+ * withdrawal contract is the same key with `visibility: 'hidden'`; a null
+ * there throws and freezes the session's whole chat pipeline), while the
+ * speech row or the cancel's own affordances carry the outcome.
+ */
+export const roomRunDefinition = {
+    kind: 'room-run',
+    target: 'chat',
+    match: event => event.type === 'room/run-state'
+        ? {
+            id: `${event.data.member}:${event.data.startedAt}`,
+            role: event.data.state === 'running' ? 'start' : 'update',
+        }
+        : null,
+    start: (_context, match) => {
+        const event = match.event;
+        if (event.type !== 'room/run-state')
+            throw new Error('room-run start requires a room/run-state event');
+        return {
+            seq: event.seq,
+            time: event.time,
+            member: event.data.member,
+            startedAt: event.data.startedAt,
+            state: event.data.state,
+        };
+    },
+    update: (context, match) => {
+        const event = match.event;
+        if (event.type !== 'room/run-state')
+            return context.state;
+        const { error: _error, elapsedMs: _elapsed, ...previous } = context.state;
+        return {
+            ...previous,
+            state: event.data.state,
+            ...event.data.elapsedMs === undefined ? {} : { elapsedMs: event.data.elapsedMs },
+            ...event.data.error === undefined ? {} : { error: event.data.error },
+        };
+    },
+    buildViewNode: context => viewNode(context, 'room-run', context.state !== undefined && (context.state.state === 'done' || context.state.state === 'cancelled')
+        ? 'hidden'
+        : 'visible'),
+};
+/**
+ * The boundary Definition: one single-event Context per member-added (cli
+ * members only — the auto-seated main agent is skipped) or member-removed
+ * event. `room/dispatch` stays unclaimed: the human's @-message renders
+ * through the official user node (it is also appended as `user/message`).
+ */
+export const roomEventDefinition = {
+    kind: 'room-event',
+    target: 'chat',
+    match: (event) => {
+        switch (event.type) {
+            case 'room/member-added':
+                return event.data.kind === 'main-agent' ? null : { id: String(event.seq), role: 'start' };
+            case 'room/member-removed':
+                return { id: String(event.seq), role: 'start' };
+            default:
+                return null;
+        }
+    },
+    start: (_context, match) => {
+        const event = match.event;
+        switch (event.type) {
+            case 'room/member-added':
+                return {
+                    seq: event.seq,
+                    time: event.time,
+                    sub: 'member-added',
+                    member: event.data.name,
+                    invitedBy: event.data.invitedBy,
+                    ...event.data.provider === undefined ? {} : { provider: event.data.provider },
+                };
+            case 'room/member-removed':
+                return { seq: event.seq, time: event.time, sub: 'member-removed', member: event.data.name };
+            default:
+                throw new Error('room-event start requires a room boundary event');
+        }
+    },
+    update: context => context.state,
+    buildViewNode: context => viewNode(context, 'room-event'),
+};
+/**
+ * The relay Definition: one Context per relay (matched on the relay id),
+ * started by the `room/relay` event (pending) and updated by each
+ * `room/relay-resolved` edge — the gate row's state folds in place.
+ */
+export const roomRelayDefinition = {
+    kind: 'room-relay',
+    target: 'chat',
+    match: (event) => {
+        switch (event.type) {
+            case 'room/relay':
+                return { id: event.data.id, role: 'start' };
+            case 'room/relay-resolved':
+                return { id: event.data.id, role: 'update' };
+            default:
+                return null;
+        }
+    },
+    start: (_context, match) => {
+        const event = match.event;
+        if (event.type !== 'room/relay')
+            throw new Error('room-relay start requires a room/relay event');
+        return {
+            seq: event.seq,
+            time: event.time,
+            relayId: event.data.id,
+            from: event.data.from,
+            to: event.data.to,
+            content: event.data.content,
+            state: 'pending',
+        };
+    },
+    update: (context, match) => {
+        const event = match.event;
+        if (event.type !== 'room/relay-resolved')
+            return context.state;
+        return { ...context.state, seq: event.seq, state: event.data.state };
+    },
+    buildViewNode: context => viewNode(context, 'room-relay'),
+};
+/**
+ * The task-advance Definition: one Context per task (matched on the task id),
+ * started by the `room/task-added` event and updated by each
+ * `room/task-updated` edge. The node stays HIDDEN while the task is open or
+ * cancelled and materializes — at the closing event's seq, so the line sits
+ * at the moment of completion — only when the task closes done: the dim
+ * advance line `✓ ada 完成了「API 定稿」── 目标进度 2/5`. (The goal progress
+ * suffix is computed by the renderer from the room store, not folded here.)
+ */
+export const roomTaskLineDefinition = {
+    kind: 'room-task-line',
+    target: 'chat',
+    match: (event) => {
+        switch (event.type) {
+            case 'room/task-added':
+                return { id: event.data.id, role: 'start' };
+            case 'room/task-updated':
+                return { id: event.data.id, role: 'update' };
+            default:
+                return null;
+        }
+    },
+    start: (_context, match) => {
+        const event = match.event;
+        if (event.type !== 'room/task-added')
+            throw new Error('room-task-line start requires a room/task-added event');
+        return {
+            seq: event.seq,
+            time: event.time,
+            taskId: event.data.id,
+            member: event.data.member,
+            title: event.data.title,
+            status: event.data.status,
+        };
+    },
+    update: (context, match) => {
+        const event = match.event;
+        if (event.type !== 'room/task-updated')
+            return context.state;
+        return { ...context.state, seq: event.seq, time: event.time, status: event.data.status };
+    },
+    buildViewNode: context => viewNode(context, 'room-task-line', context.state !== undefined && context.state.status === 'done' ? 'visible' : 'hidden'),
+};

package/lib/types/client/preset-visibility.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The preset-composition visibility of room's SESSION chrome (M3' self-hide,
+ * the mode-switcher proposal's "组合里有我的行"): the invite chip and the
+ * members tab show exactly when the CURRENT session's preset composition
+ * names the `@khorsheed/dsh-room-tool` row — the preset composition file is
+ * the single source of truth, read from the official `pluginInventory`
+ * Remote (the same criterion the worktrees badge implements; inlined here
+ * rather than extracted into a helper package, per the proposal's M3'
+ * deferral). Every unreadable path fails OPEN (visible): a host without the
+ * pluginInventory namespace, a pending/failed RPC, a missing or `broken`
+ * preset group, and sessions with no preset at all. An ACTUAL room session
+ * always shows its chrome regardless of preset — the gate hides the dev
+ * affordance in sessions that never granted it, never breaks an existing
+ * room (the E1 regression rule).
+ * @module @khorsheed/dsh-room/client/preset-visibility
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+/** The composition criterion's row: room's companion tool package. */
+export declare const ROOM_TOOL_ROW_MODULE = "@khorsheed/dsh-room-tool";
+/**
+ * Minimal structural mirror of the official pluginInventory snapshot — only
+ * the agentPresets slice the criterion reads (duck-typed, host-version
+ * tolerant: an extra field never breaks a structural read).
+ */
+export interface RoomPluginInventorySnapshot {
+    readonly agentPresets?: readonly {
+        readonly id: string;
+        readonly broken?: string;
+        readonly rows: readonly {
+            readonly moduleName: string;
+        }[];
+    }[];
+}
+/** The visibility face the gated surfaces consume. */
+export interface RoomChromeVisibility {
+    /**
+     * Whether room's session chrome shows for one session.
+     * @param sessionId - the session being rendered (undefined = no session
+     *   context — fail-open, so registration-shape probes keep their entries).
+     */
+    show: (sessionId: SessionId | undefined) => boolean;
+    /** Subscribe to criterion-input changes (session switches, the inventory answer). */
+    subscribe: (listener: () => void) => () => void;
+}
+/**
+ * The session-chrome visibility controller: one inventory fetch per page
+ * (composition data changes only with preset files, which a reload re-reads
+ * anyway), re-evaluated by its consumers on every session switch.
+ */
+export declare class RoomPresetVisibility implements RoomChromeVisibility {
+    private readonly ctx;
+    private readonly isRoom;
+    /** The inventory answer; null while pending/failed and on namespace-less hosts. */
+    private composition;
+    private readonly listeners;
+    /**
+     * @param ctx - client root context.
+     * @param isRoom - the RoomStore's cached room verdict (the E1 escape).
+     */
+    constructor(ctx: Context, isRoom: (sessionId: SessionId) => boolean);
+    show(sessionId: SessionId | undefined): boolean;
+    subscribe(listener: () => void): () => void;
+    private notify;
+}
+/**
+ * The members tab's registration toggle: the `conversation.view` tab strip's
+ * BUTTONS enumerate the slot's registrations (ui-conversation's `viewTabs()`
+ * has no per-session predicate), so a hidden tab means NO registration — a
+ * component returning null would leave the button with an empty body. The
+ * toggle registers exactly while the criterion passes for the current
+ * session and disposes otherwise; the slot's own subscription re-renders the
+ * strip (the same re-registration mechanism the composer takeover's
+ * promotion bump uses).
+ */
+export declare class RegistrationToggle {
+    private readonly register;
+    private readonly show;
+    private dispose;
+    private ready;
+    /**
+     * @param register - mounts the entry and returns its disposer.
+     * @param show - the current decision (re-read on every sync).
+     */
+    constructor(register: () => () => void, show: () => boolean);
+    /** The slot declaration appeared (slots.inject's arm) — decisions may register now. */
+    setReady(ready: boolean): void;
+    /** Re-evaluate: register while shown and ready, dispose otherwise. */
+    sync(): void;
+}
+//# sourceMappingURL=preset-visibility.d.ts.map

package/lib/types/client/preset-visibility.js

@@ -0,0 +1,113 @@
+/** The composition criterion's row: room's companion tool package. */
+export const ROOM_TOOL_ROW_MODULE = '@khorsheed/dsh-room-tool';
+/** The current session's agent preset, the badge's dual read per host line. */
+function presetOf(row) {
+    const value = row
+        ?.projectionValues?.agentPreset
+        ?? row?.agentPreset;
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * The session-chrome visibility controller: one inventory fetch per page
+ * (composition data changes only with preset files, which a reload re-reads
+ * anyway), re-evaluated by its consumers on every session switch.
+ */
+export class RoomPresetVisibility {
+    ctx;
+    isRoom;
+    /** The inventory answer; null while pending/failed and on namespace-less hosts. */
+    composition = null;
+    listeners = new Set();
+    /**
+     * @param ctx - client root context.
+     * @param isRoom - the RoomStore's cached room verdict (the E1 escape).
+     */
+    constructor(ctx, isRoom) {
+        this.ctx = ctx;
+        this.isRoom = isRoom;
+        // The OFFICIAL pluginInventory namespace, probed through ctx.get (never
+        // injected — declaring 'remote.pluginInventory' would pend the whole
+        // client on a host without it, and the criterion must fail open there).
+        const pluginInventory = ctx.get('remote.pluginInventory');
+        if (pluginInventory !== undefined) {
+            void pluginInventory.list().then(result => {
+                if (!result.ok)
+                    return;
+                this.composition = result.value;
+                this.notify();
+            }).catch(() => { });
+        }
+        // Session switches re-decide the members tab's registration (the tab
+        // strip's buttons come from the registration, not the component).
+        ctx.effect(() => ctx.sessions.list.subscribe(() => { this.notify(); }), 'room: preset-visibility session follower');
+    }
+    show(sessionId) {
+        if (sessionId === undefined)
+            return true;
+        // An actual room keeps its chrome whatever its preset granted (E1).
+        if (this.isRoom(sessionId))
+            return true;
+        const preset = presetOf(this.ctx.sessions.list.getSnapshot().byId[sessionId]);
+        if (preset === undefined)
+            return true;
+        if (this.composition === null)
+            return true;
+        const group = this.composition.agentPresets?.find(candidate => candidate.id === preset);
+        if (group === undefined || group.broken !== undefined)
+            return true;
+        return group.rows.some(row => row.moduleName === ROOM_TOOL_ROW_MODULE);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * The members tab's registration toggle: the `conversation.view` tab strip's
+ * BUTTONS enumerate the slot's registrations (ui-conversation's `viewTabs()`
+ * has no per-session predicate), so a hidden tab means NO registration — a
+ * component returning null would leave the button with an empty body. The
+ * toggle registers exactly while the criterion passes for the current
+ * session and disposes otherwise; the slot's own subscription re-renders the
+ * strip (the same re-registration mechanism the composer takeover's
+ * promotion bump uses).
+ */
+export class RegistrationToggle {
+    register;
+    show;
+    dispose;
+    ready = false;
+    /**
+     * @param register - mounts the entry and returns its disposer.
+     * @param show - the current decision (re-read on every sync).
+     */
+    constructor(register, show) {
+        this.register = register;
+        this.show = show;
+    }
+    /** The slot declaration appeared (slots.inject's arm) — decisions may register now. */
+    setReady(ready) {
+        this.ready = ready;
+        if (!ready && this.dispose !== undefined) {
+            this.dispose();
+            this.dispose = undefined;
+        }
+        this.sync();
+    }
+    /** Re-evaluate: register while shown and ready, dispose otherwise. */
+    sync() {
+        if (!this.ready)
+            return;
+        if (this.show()) {
+            this.dispose ??= this.register();
+        }
+        else if (this.dispose !== undefined) {
+            this.dispose();
+            this.dispose = undefined;
+        }
+    }
+}

package/lib/types/client/request-ids.d.ts

@@ -0,0 +1,7 @@
+/** Keep one retry identity per room draft until the server acknowledges it. */
+export declare class RoomRequestIds {
+    private readonly pending;
+    forInput(sessionId: string, text: string, targets?: readonly string[]): string;
+    complete(sessionId: string, id: string): void;
+}
+//# sourceMappingURL=request-ids.d.ts.map

package/lib/types/client/request-ids.js

@@ -0,0 +1,21 @@
+/** Keep one retry identity per room draft until the server acknowledges it. */
+export class RoomRequestIds {
+    pending = new Map();
+    forInput(sessionId, text, targets = []) {
+        const signature = JSON.stringify({ text: text.trim(), targets: [...new Set(targets)].sort() });
+        const known = this.pending.get(sessionId);
+        if (known?.signature === signature)
+            return known.id;
+        const id = typeof globalThis.crypto.randomUUID === 'function' ? globalThis.crypto.randomUUID()
+            : Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), value => value.toString(16).padStart(2, '0')).join('');
+        this.pending.delete(sessionId);
+        this.pending.set(sessionId, { signature, id });
+        if (this.pending.size > 128)
+            this.pending.delete(this.pending.keys().next().value);
+        return id;
+    }
+    complete(sessionId, id) {
+        if (this.pending.get(sessionId)?.id === id)
+            this.pending.delete(sessionId);
+    }
+}

package/lib/types/client/room-store.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Client-side room state store: the synchronous cache the composer chain
+ * selector reads (selectors cannot await), plus the per-session RoomState
+ * the room components render. Fed by the mounted room Remote: a first pull
+ * (`isRoom`, then `getState` when true) per session, a refresh after every
+ * own mutation, a realtime refresh trigger off the current session's live
+ * conversation feed, and a light 2s poll of `getState` only while the
+ * CURRENT session is a room with a running member (no running members, no
+ * polling). The live feed: the host pushes EVERY session event — room
+ * journal appends included — as `session/event` frames, which the runtime
+ * folds into the client Session's conversation snapshot; subscribing that
+ * snapshot and refreshing (300ms debounced) is how host-side mutations the
+ * client never initiated (the `room_task`/`room_invite` tools, the
+ * local-agent member bridge) land in the dock within a beat. A cache miss
+ * reads as `undefined`, and the composer selector declines on a miss: the
+ * first instant of a freshly opened room shows the official input bar until
+ * the first pull lands (accepted, documented).
+ * @module @khorsheed/dsh-room/client/room-store
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { RoomGetStateRequest, RoomGetStateResult, RoomIsRoomRequest, RoomState } from '../types.ts';
+/**
+ * The session the main view shows, read off both host lines: alpha.2 deleted
+ * the list's `current` for the per-row `retainedBy.mainView` reference count;
+ * 0.1.5 carries only `current`.
+ * @param list - the sessions list snapshot.
+ * @returns the main-view session id, or undefined when no session is shown.
+ */
+export declare function mainSessionId(list: SessionListState): SessionId | undefined;
+/** The slice of the mounted room Remote the store reads. */
+export interface RoomGateway {
+    isRoom(request: RoomIsRoomRequest): Promise<RemoteResult<boolean>>;
+    getState(request: RoomGetStateRequest): Promise<RemoteResult<RoomGetStateResult>>;
+}
+/** Poll cadence while the current room has running members. */
+export declare const ROOM_POLL_INTERVAL_MS = 2000;
+/**
+ * Debounce coalescing the live-feed refresh: one room journal append usually
+ * arrives inside a burst of session events (the tool call, its result, the
+ * task/task-update edges), so the refresh waits for a quiet beat.
+ */
+export declare const ROOM_LIVE_REFRESH_DEBOUNCE_MS = 300;
+export declare class RoomStore {
+    private readonly ctx;
+    private readonly gateway;
+    private readonly room;
+    private readonly states;
+    private readonly listeners;
+    private poller;
+    private current;
+    /** The session the live feed is subscribed to (undefined = unattached). */
+    private liveAttached;
+    private liveUnsubscribe;
+    private liveTimer;
+    /**
+     * @param ctx - client root context (the sessions list feed).
+     * @param gateway - the mounted room Remote, undefined when the mount failed.
+     */
+    constructor(ctx: Context, gateway: RoomGateway | undefined);
+    /**
+     * Follow the current session: a new current room session gets its first
+     * pull and its live-feed subscription, and polling re-evaluates on every
+     * switch.
+     * @returns disposer (unsubscribe everything + stop polling).
+     */
+    start(): () => void;
+    /**
+     * The composer selector's synchronous read.
+     * @param sessionId - session to probe.
+     * @returns cached verdict, or undefined while the first pull is in flight.
+     */
+    isRoomCached(sessionId: SessionId): boolean | undefined;
+    /**
+     * The cached room state (stable reference between refreshes — safe as a
+     * useSyncExternalStore snapshot).
+     * @param sessionId - room session.
+     * @returns the cached state, or undefined before the first successful pull.
+     */
+    getCached(sessionId: SessionId): RoomState | undefined;
+    /**
+     * Subscribe to cache changes.
+     * @param listener - called after any map mutation.
+     * @returns unsubscribe.
+     */
+    readonly subscribe: (listener: () => void) => (() => void);
+    /**
+     * First pull for a session: isRoom, then getState when it is one.
+     * No-ops on a cached verdict.
+     * @param sessionId - session to ensure.
+     */
+    ensure(sessionId: SessionId): Promise<void>;
+    /**
+     * Re-pull the room state (after an own mutation, a live-feed nudge, or a
+     * poll tick).
+     * @param sessionId - room session.
+     */
+    refresh(sessionId: SessionId): Promise<void>;
+    /**
+     * Subscribe the CURRENT session's live conversation feed so host-side
+     * journal appends nudge a refresh. The session binding is minted lazily by
+     * the runtime (it can lag the list's current flip), so every completed pull
+     * re-attempts the attach; an unattached store simply keeps its other
+     * triggers until one lands.
+     */
+    private attachLive;
+    /** Drop the live-feed subscription and any pending debounced refresh. */
+    private detachLive;
+    /**
+     * One live-feed nudge, debounced so an event burst costs one probe: a known
+     * room refreshes its state; a session cached NOT a room re-probes `isRoom`
+     * (a promotion lands as a host-side `room/created` append the client never
+     * initiated — the room_invite/room_message tools promote in place); a
+     * unknown verdict retries ensure after the same debounce.
+     */
+    private onLiveEvent;
+    /**
+     * Re-probe a cached-non-room session's verdict: a promotion flips the cache
+     * and pulls the state (the composer takeover follows on the next notify).
+     * @param sessionId - the session whose verdict may have changed.
+     */
+    private reprobe;
+    private notify;
+    /**
+     * Called when a session's verdict flips unknown/false → true (an in-place
+     * promotion): the composer chain elects at RENDER time and nothing
+     * re-renders the outlet for a promotion of an idle session, so the client
+     * wires this to re-register the composer entry (a slot version bump
+     * re-renders — and re-elects — the outlet).
+     */
+    onPromoted: (() => void) | undefined;
+    private adjustPolling;
+    private stopPolling;
+}
+//# sourceMappingURL=room-store.d.ts.map