@crazx/dsh-api-session-controller 0.1.2-alpha.3.zw.1

package/lib/types/client/sessions/notifier.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Batches structural updates in microtasks and stream updates by animation
+ * frame. Reads may rebuild a dirty snapshot without consuming the pending
+ * subscriber notification.
+ */
+export declare class Notifier {
+    private readonly rebuild;
+    private listeners;
+    private dirty;
+    private notifyPending;
+    private scheduled;
+    private scheduleGeneration;
+    /** @param rebuild - snapshot rebuild function injected by the owner (writes the owner's snapshotCache). */
+    constructor(rebuild: () => void);
+    /**
+     * uSES subscription entry.
+     * @param listener - change callback.
+     * @returns the unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /** Mark the snapshot dirty and notify in a microtask. */
+    markDirty(): void;
+    /** Mark the snapshot dirty and publish cumulative state at most once per frame. */
+    markFrameDirty(): void;
+    /**
+     * Synchronous flush: controlled-input writes must notify in the same tick as
+     * onChange, or React rolls the DOM back to the stale value and the caret jumps to the end.
+     */
+    notifyNow(): void;
+    /**
+     * Pre-getSnapshot check: rebuild synchronously when dirty (read path
+     * before first subscribe / while unobserved). Notification stays pending.
+     */
+    ensureFresh(): void;
+    private schedule;
+    private invalidateSchedule;
+    private flush;
+}
+//# sourceMappingURL=notifier.d.ts.map

package/lib/types/client/sessions/notifier.js

@@ -0,0 +1,98 @@
+import { notifySubscribers } from '@deepseek-ai/dsh-client-store';
+/**
+ * Batches structural updates in microtasks and stream updates by animation
+ * frame. Reads may rebuild a dirty snapshot without consuming the pending
+ * subscriber notification.
+ */
+export class Notifier {
+    rebuild;
+    listeners = new Set();
+    dirty = false;
+    notifyPending = false;
+    scheduled = 'none';
+    scheduleGeneration = 0;
+    /** @param rebuild - snapshot rebuild function injected by the owner (writes the owner's snapshotCache). */
+    constructor(rebuild) {
+        this.rebuild = rebuild;
+    }
+    /**
+     * uSES subscription entry.
+     * @param listener - change callback.
+     * @returns the unsubscribe function.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Mark the snapshot dirty and notify in a microtask. */
+    markDirty() {
+        this.dirty = true;
+        this.notifyPending = true;
+        if (this.scheduled === 'microtask')
+            return;
+        this.schedule('microtask');
+    }
+    /** Mark the snapshot dirty and publish cumulative state at most once per frame. */
+    markFrameDirty() {
+        this.dirty = true;
+        this.notifyPending = true;
+        if (this.scheduled !== 'none')
+            return;
+        this.schedule(typeof globalThis.requestAnimationFrame === 'function' ? 'frame' : 'microtask');
+    }
+    /**
+     * Synchronous flush: controlled-input writes must notify in the same tick as
+     * onChange, or React rolls the DOM back to the stale value and the caret jumps to the end.
+     */
+    notifyNow() {
+        this.dirty = true;
+        this.notifyPending = true;
+        this.invalidateSchedule();
+        this.flush();
+    }
+    /**
+     * Pre-getSnapshot check: rebuild synchronously when dirty (read path
+     * before first subscribe / while unobserved). Notification stays pending.
+     */
+    ensureFresh() {
+        if (!this.dirty)
+            return;
+        this.dirty = false;
+        this.rebuild();
+    }
+    schedule(kind) {
+        const generation = ++this.scheduleGeneration;
+        this.scheduled = kind;
+        const publish = () => {
+            if (generation !== this.scheduleGeneration)
+                return;
+            this.scheduled = 'none';
+            this.flush();
+        };
+        if (kind === 'frame') {
+            globalThis.requestAnimationFrame(publish);
+        }
+        else {
+            queueMicrotask(publish);
+        }
+    }
+    invalidateSchedule() {
+        this.scheduleGeneration++;
+        this.scheduled = 'none';
+    }
+    flush() {
+        if (!this.notifyPending)
+            return;
+        if (this.listeners.size === 0)
+            return; // lazy: dirty (if still set) rebuilds on next getSnapshot
+        this.notifyPending = false;
+        if (this.dirty) {
+            this.dirty = false;
+            this.rebuild();
+        }
+        notifySubscribers(this.listeners, '[session-controller]');
+    }
+}
+//# sourceMappingURL=notifier.js.map

package/lib/types/client/sessions/projection-store.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Generic per-session projection value store (push model; see the
+ * session-projection subsystem page, docs/subsystems/session-projection.md):
+ * the host is the only computation site; the client holds finished
+ * whole values per key — `key → { value, seq }` — seeded by a follow opening
+ * baseline and updated by Session Controller `projection` frames,
+ * under the single rule **higher seq wins**. No client-side domain folding
+ * exists: a domain ships projection support with zero client code. Per-key
+ * bare observable faces feed `useProjection` (ui-renderer binds them).
+ */
+import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+export type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types';
+/**
+ * The fifth framework hook seat (see the session-projection subsystem page,
+ * docs/subsystems/session-projection.md): key-addressed
+ * projection reader delivered through the standard kit. `undefined` uniformly
+ * means capability absent — host unit unmounted, or no baseline/frame has
+ * carried the key yet. The selector overload mirrors useSession (per-key uSES
+ * binding; reference stability holds because a key's value reference changes
+ * only when a frame or baseline lands).
+ */
+export type UseProjection = {
+    <K extends Extract<keyof SessionProjectionMap, string>>(key: K): SessionProjectionMap[K] | undefined;
+    <K extends Extract<keyof SessionProjectionMap, string>, S>(key: K, selector: (value: SessionProjectionMap[K] | undefined) => S, eq?: (a: S, b: S) => boolean): S;
+};
+/**
+ * Follow-opening projection baseline, restated here so the
+ * React-free store depends only on the type table, not the wire package's
+ * response vocabulary.
+ */
+export interface ProjectionsBaseline {
+    /** The consistent-cut seq (equals the window tail seq by construction). */
+    asOfSeq: number;
+    /** Whole current values by key; a registered key absent here means the capability is absent. */
+    values: Readonly<Record<string, unknown>>;
+}
+/**
+ * One session's projection values. Framework semantics, uniform across every
+ * key: a baseline seeds rows at its cut, a push frame updates one row, and in
+ * both paths a lower-or-equal seq loses — a replayed frame cannot regress a
+ * value, a stale baseline cannot overwrite a newer frame. A key the store has
+ * never seen reads `undefined` (capability absent). Faces are identity-stable
+ * per key (create-on-demand, cached) so the React side binds each exactly
+ * once; the store-level channel (`subscribeAny`) serves coarse consumers (the
+ * manager's list projection reads the `title` key).
+ */
+export declare class ProjectionValueStore {
+    private readonly rows;
+    private readonly channels;
+    private valuesCache;
+    /** Coarse any-key channel (no snapshot cache to rebuild: reads hit rows directly). */
+    private readonly anyNotifier;
+    /**
+     * Key-addressed bare observable face (the useProjection resolution path).
+     * Always defined — absence is an `undefined` snapshot, never a missing
+     * face, so a component may subscribe before the key ever carries a value.
+     * @param key - projection key.
+     * @returns the identity-stable face for this key.
+     */
+    faceOf(key: string): ObservableSnapshot<unknown>;
+    /**
+     * Current whole value for a key (erased framework read; typed reads go
+     * through `useProjection`'s map lookup).
+     * @param key - projection key.
+     * @returns the value, or undefined while the key is absent.
+     */
+    get(key: string): unknown;
+    /**
+     * Read every current projection value as one reference-stable snapshot.
+     * @returns The same frozen value map until a row changes.
+     */
+    values(): Readonly<Partial<SessionProjectionMap>>;
+    /**
+     * Subscribe to any-key changes (microtask-batched) — the manager's list
+     * rebuild channel.
+     * @param listener - change callback.
+     * @returns the unsubscribe function.
+     */
+    subscribeAny(listener: () => void): () => void;
+    /**
+     * Apply one finished value from the Session control stream.
+     * @param key - projection key.
+     * @param value - whole value computed by the host unit.
+     * @param seq - the unit's watermark at emission.
+     */
+    apply(key: string, value: unknown, seq: number): void;
+    /**
+     * Seed from a history tail page's projections block: every carried key
+     * lands under the same seq rule as frames; a key the block omits is
+     * capability-absent as of the cut — its row clears unless a newer frame
+     * already superseded the cut (a stale baseline can neither overwrite nor
+     * clear newer values).
+     * @param baseline - the response's projections block.
+     */
+    seed(baseline: ProjectionsBaseline): void;
+    /**
+     * Drop rows beyond a replacement control baseline. Such rows describe
+     * process state the Host lost before persisting it and would otherwise
+     * outrank recomputed lower-seq values forever. The caller seeds the new
+     * baseline immediately afterward.
+     * @param lastSeq - highest durable sequence reflected by the baseline.
+     */
+    truncate(lastSeq: number): void;
+    private changed;
+    private channel;
+}
+//# sourceMappingURL=projection-store.d.ts.map

package/lib/types/client/sessions/projection-store.js

@@ -0,0 +1,129 @@
+import { Notifier } from "./notifier.js";
+/**
+ * One session's projection values. Framework semantics, uniform across every
+ * key: a baseline seeds rows at its cut, a push frame updates one row, and in
+ * both paths a lower-or-equal seq loses — a replayed frame cannot regress a
+ * value, a stale baseline cannot overwrite a newer frame. A key the store has
+ * never seen reads `undefined` (capability absent). Faces are identity-stable
+ * per key (create-on-demand, cached) so the React side binds each exactly
+ * once; the store-level channel (`subscribeAny`) serves coarse consumers (the
+ * manager's list projection reads the `title` key).
+ */
+export class ProjectionValueStore {
+    rows = new Map();
+    channels = new Map();
+    valuesCache;
+    /** Coarse any-key channel (no snapshot cache to rebuild: reads hit rows directly). */
+    anyNotifier = new Notifier(() => { });
+    /**
+     * Key-addressed bare observable face (the useProjection resolution path).
+     * Always defined — absence is an `undefined` snapshot, never a missing
+     * face, so a component may subscribe before the key ever carries a value.
+     * @param key - projection key.
+     * @returns the identity-stable face for this key.
+     */
+    faceOf(key) {
+        return this.channel(key).face;
+    }
+    /**
+     * Current whole value for a key (erased framework read; typed reads go
+     * through `useProjection`'s map lookup).
+     * @param key - projection key.
+     * @returns the value, or undefined while the key is absent.
+     */
+    get(key) {
+        return this.rows.get(key)?.value;
+    }
+    /**
+     * Read every current projection value as one reference-stable snapshot.
+     * @returns The same frozen value map until a row changes.
+     */
+    values() {
+        if (this.valuesCache === undefined) {
+            this.valuesCache = Object.freeze(Object.fromEntries([...this.rows].map(([key, row]) => [key, row.value])));
+        }
+        return this.valuesCache;
+    }
+    /**
+     * Subscribe to any-key changes (microtask-batched) — the manager's list
+     * rebuild channel.
+     * @param listener - change callback.
+     * @returns the unsubscribe function.
+     */
+    subscribeAny(listener) {
+        return this.anyNotifier.subscribe(listener);
+    }
+    /**
+     * Apply one finished value from the Session control stream.
+     * @param key - projection key.
+     * @param value - whole value computed by the host unit.
+     * @param seq - the unit's watermark at emission.
+     */
+    apply(key, value, seq) {
+        const row = this.rows.get(key);
+        if (row !== undefined && seq <= row.seq)
+            return; // higher seq wins; replays and stale frames drop
+        this.rows.set(key, { value, seq });
+        this.changed(key);
+    }
+    /**
+     * Seed from a history tail page's projections block: every carried key
+     * lands under the same seq rule as frames; a key the block omits is
+     * capability-absent as of the cut — its row clears unless a newer frame
+     * already superseded the cut (a stale baseline can neither overwrite nor
+     * clear newer values).
+     * @param baseline - the response's projections block.
+     */
+    seed(baseline) {
+        // Erased walk: the framework crosses the open key space; per-key typing
+        // is re-established at the consumer (useProjection's map lookup).
+        const values = baseline.values;
+        for (const key of Object.keys(values))
+            this.apply(key, values[key], baseline.asOfSeq);
+        for (const [key, row] of this.rows) {
+            if (Object.hasOwn(values, key))
+                continue;
+            if (row.seq > baseline.asOfSeq)
+                continue;
+            this.rows.delete(key);
+            this.changed(key);
+        }
+    }
+    /**
+     * Drop rows beyond a replacement control baseline. Such rows describe
+     * process state the Host lost before persisting it and would otherwise
+     * outrank recomputed lower-seq values forever. The caller seeds the new
+     * baseline immediately afterward.
+     * @param lastSeq - highest durable sequence reflected by the baseline.
+     */
+    truncate(lastSeq) {
+        for (const [key, row] of this.rows) {
+            if (row.seq <= lastSeq)
+                continue;
+            this.rows.delete(key);
+            this.changed(key);
+        }
+    }
+    changed(key) {
+        this.valuesCache = undefined;
+        this.channels.get(key)?.notifier.markDirty();
+        this.anyNotifier.markDirty();
+    }
+    channel(key) {
+        let channel = this.channels.get(key);
+        if (channel === undefined) {
+            // The notifier only batches (no snapshot cache to rebuild: faces read rows directly).
+            const notifier = new Notifier(() => { });
+            channel = {
+                notifier,
+                face: {
+                    getSnapshot: () => this.rows.get(key)?.value,
+                    subscribe: listener => notifier.subscribe(listener),
+                },
+            };
+            this.channels.set(key, channel);
+        }
+        return channel;
+    }
+}
+//# sourceMappingURL=projection-store.js.map

package/lib/types/client/sessions/queue-mirror.d.ts

@@ -0,0 +1,26 @@
+import type { SessionQueuedItem } from '../../types.ts';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { QueuedMessage } from '../contract/snapshot.ts';
+type QueueItems = readonly SessionQueuedItem[];
+/** Authoritative transient queue projection and durable steering handoff. */
+export declare class SessionQueueMirror {
+    private current;
+    /**
+     * Return the current immutable queue projection.
+     * @returns current queue rows.
+     */
+    snapshot(): readonly QueuedMessage[];
+    /**
+     * Replace from one authoritative stream queue frame.
+     * @param items - complete host queue snapshot.
+     */
+    replace(items: QueueItems): void;
+    /**
+     * Retire a transient steering row once its durable message enters the log.
+     * @param event - newly contiguous durable Session event.
+     * @returns whether the projection changed.
+     */
+    acceptDurable(event: SessionEvent): boolean;
+}
+export {};
+//# sourceMappingURL=queue-mirror.d.ts.map

package/lib/types/client/sessions/queue-mirror.js

@@ -0,0 +1,61 @@
+const QUEUE_PREVIEW_CHARS = 200;
+// Image blocks are excluded: queue presentation renders them as thumbnails
+// from `content`, so the text preview covers only what has no visual form.
+function previewOf(content) {
+    const flat = content
+        .filter(block => block.type !== 'image')
+        .map(block => (block.type === 'text' ? block.text : `[${block.type}]`))
+        .join(' ').replace(/\s+/g, ' ').trim();
+    const chars = Array.from(flat);
+    return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join('')}…` : flat;
+}
+function textOf(content) {
+    if (!content.every(block => block.type === 'text'))
+        return null;
+    return content.map(block => block.text).join('');
+}
+/** Authoritative transient queue projection and durable steering handoff. */
+export class SessionQueueMirror {
+    current = [];
+    /**
+     * Return the current immutable queue projection.
+     * @returns current queue rows.
+     */
+    snapshot() {
+        return this.current;
+    }
+    /**
+     * Replace from one authoritative stream queue frame.
+     * @param items - complete host queue snapshot.
+     */
+    replace(items) {
+        this.current = items.map((item) => {
+            const content = item.message.content;
+            return {
+                id: item.id,
+                messageId: item.message.id,
+                placement: item.placement,
+                ...(item.rpcId === undefined ? {} : { rpcId: item.rpcId }),
+                content,
+                preview: previewOf(content),
+                text: textOf(content),
+            };
+        });
+    }
+    /**
+     * Retire a transient steering row once its durable message enters the log.
+     * @param event - newly contiguous durable Session event.
+     * @returns whether the projection changed.
+     */
+    acceptDurable(event) {
+        if (event.type !== 'user/message')
+            return false;
+        const messageId = event.data.id;
+        const index = this.current.findIndex(item => item.placement === 'steering' && item.messageId === messageId);
+        if (index < 0)
+            return false;
+        this.current = this.current.filter((_item, candidate) => candidate !== index);
+        return true;
+    }
+}
+//# sourceMappingURL=queue-mirror.js.map

package/lib/types/client/sessions/remotes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Remote namespaces the Session cluster calls. One parameter for one concept:
+ * the generated surface a Session and its manager reach the Host through.
+ *
+ * @module @deepseek-ai/dsh-api-session-controller/client/sessions/remotes
+ */
+import type { EncodedImageAttachment } from '@deepseek-ai/dsh-attachment/types';
+import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { SubagentCatalog, SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from '@deepseek-ai/dsh-subagent/client';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { SessionRemote } from '../transport.ts';
+/** Narrow Commands namespace consumed by a Client Session. */
+export interface SessionCommandsRemote {
+    execute(agentId: SessionId, line: string, images: readonly EncodedImageAttachment[], signal?: AbortSignal): Promise<RemoteResult<object | undefined>>;
+}
+/** Narrow subagent namespace consumed by a Client Session and its manager. */
+export interface SessionSubagentsRemote {
+    list(parentSessionId: SessionId, signal?: AbortSignal): Promise<RemoteResult<SubagentCatalog>>;
+    prompt(request: SubagentPromptRequest, signal?: AbortSignal): Promise<RemoteResult<SubagentPromptReceipt>>;
+    interruptByParent(childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable'): Promise<RemoteResult<SubagentInterruptReceipt>>;
+}
+/** Generated Remote namespaces consumed by the Client Session object layer. */
+export interface SessionRemotes {
+    readonly $stream: ClientRemote['$stream'];
+    readonly commands: SessionCommandsRemote;
+    readonly session: SessionRemote;
+    readonly subagents: SessionSubagentsRemote;
+}
+//# sourceMappingURL=remotes.d.ts.map

package/lib/types/client/sessions/remotes.js

@@ -0,0 +1,8 @@
+/**
+ * Remote namespaces the Session cluster calls. One parameter for one concept:
+ * the generated surface a Session and its manager reach the Host through.
+ *
+ * @module @deepseek-ai/dsh-api-session-controller/client/sessions/remotes
+ */
+export {};
+//# sourceMappingURL=remotes.js.map