@addozhang/dsh-discord 0.4.0 → 0.5.0-alpha.2

package/lib/dsh/host-events.js

@@ -0,0 +1,279 @@
+/**
+ * The 0.1.6 host event bridge: fans the per-session `session/follow`
+ * journals plus the host-wide `session/control` stream into the single
+ * frame stream the live renderer consumes (the rc.2 `apiProxy.events.mux`
+ * global stream no longer exists).
+ *
+ * Frame vocabulary is preserved verbatim (`session/event`,
+ * `session/subscribed`, `session/queue`), so `src/stream/live.ts` and its
+ * tests are untouched by the host-side rebase. Two deliberate exclusions:
+ *
+ * - `snapshot` opening windows ARE translated through the same seq
+ *   watermark as live events: the turn often completes between prompt
+ *   admission and our follow subscription, so the opening window is the
+ *   ONLY carrier of those records. The watermark (last delivered seq per
+ *   session) keeps re-subscription replays idempotent.
+ * - approval/question request frames are NOT synthesized here: the 0.1.6
+ *   host routes asks through the composed-approval model, which the
+ *   ask-wiring migration wires separately.
+ */
+/** Build the push-side of the single consumer queue. */
+function createFrameQueue() {
+    const buffered = [];
+    let notify;
+    let closed = false;
+    const queue = {
+        push(frame) {
+            if (closed)
+                return;
+            buffered.push(frame);
+            const wake = notify;
+            notify = undefined;
+            wake?.();
+        },
+        close() {
+            closed = true;
+            const wake = notify;
+            notify = undefined;
+            wake?.();
+        },
+    };
+    return {
+        ...queue,
+        iterate(signal) {
+            return {
+                async *[Symbol.asyncIterator]() {
+                    try {
+                        for (;;) {
+                            if (signal.aborted)
+                                return;
+                            while (buffered.length > 0) {
+                                // shift() cannot miss: the length guard ran first.
+                                yield buffered.shift();
+                            }
+                            if (closed)
+                                return;
+                            await new Promise(resolve => {
+                                notify = resolve;
+                                const abort = () => {
+                                    notify = undefined;
+                                    resolve();
+                                };
+                                signal.addEventListener('abort', abort, { once: true });
+                            });
+                        }
+                    }
+                    finally {
+                        queue.close();
+                    }
+                },
+            };
+        },
+    };
+}
+/** Defensive record probe: the wire is untrusted regardless of declared types. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Defensive text extraction from a queued message's JSON content parts. */
+function queueItemSummary(content) {
+    if (!Array.isArray(content))
+        return '';
+    const texts = [];
+    for (const part of content) {
+        if (typeof part !== 'object' || part === null)
+            continue;
+        const typed = part;
+        if (typed.type === 'text' && typeof typed.text === 'string')
+            texts.push(typed.text);
+    }
+    return texts.join(' ').slice(0, 200);
+}
+/**
+ * The fan-in router. `track(sessionId)` is idempotent and safe to call from
+ * every session-acquisition site (create, adopt, resume, prompt); each
+ * tracked session owns one follow loop whose frames join the shared queue.
+ */
+export function createHostEventRouter(services, options = {}) {
+    const log = options.log;
+    const tracked = new Map();
+    /** Last delivered durable seq per session: the replay-dedupe watermark. */
+    const watermark = new Map();
+    let consumer;
+    let rootSignal;
+    const startLoop = (sessionId, attempt = 0) => {
+        const per = new AbortController();
+        tracked.set(sessionId, per);
+        void (async () => {
+            if (process.env['DSH_DISCORD_TRACE'] === '1')
+                console.error(`[dsh-discord:trace] follow-start session=${sessionId.slice(0, 8)} attempt=${String(attempt)}`);
+            try {
+                consumer?.push({ type: 'session/subscribed', sessionId });
+                // The follow request MUST ask for assistant streaming: without the
+                // flag the host (alpha.2) delivers only the opening snapshot and
+                // never pushes later journal records — the live tail stays dead
+                // (diagnosis.md §D, run 2 vs run 3).
+                for await (const raw of services.follow({ address: { kind: 'session', sessionId }, assistantStream: true }, per.signal)) {
+                    if (process.env['DSH_DISCORD_TRACE'] === '1') {
+                        const dumped = JSON.stringify(raw);
+                        console.error(`[dsh-discord:trace] raw-follow-frame type=${String(isRecord(raw) ? raw['type'] : typeof raw)} frame=${dumped.length > 300 ? `${dumped.slice(0, 300)}…` : dumped}`);
+                    }
+                    if (!isRecord(raw))
+                        continue;
+                    const frame = raw;
+                    // Both the opening snapshot and live journal entries carry the
+                    // same {type, data, seq} record envelope the rc.2 mux delivered;
+                    // the seq watermark keeps replayed windows idempotent.
+                    if (frame['type'] === 'event' || frame['type'] === 'snapshot') {
+                        // Two carriers, both real-machine verified (alpha.2): snapshot
+                        // windows batch their records under `records`, while live records
+                        // arrive as single-record frames — the record rides the `event`
+                        // key of the frame itself, no array. Snapshots without a records
+                        // array stay drops (malformed), live frames become their own
+                        // one-element batch.
+                        const records = raw.records;
+                        const batch = Array.isArray(records)
+                            ? records
+                            : frame['type'] === 'event'
+                                ? [raw]
+                                : undefined;
+                        if (batch === undefined)
+                            continue;
+                        const through = watermark.get(sessionId) ?? 0;
+                        let delivered = through;
+                        for (const record of batch) {
+                            // Journal records arrive double-wrapped: {type:'event',
+                            // event:{type, seq, time, data}} — the wire event rides the
+                            // `event` key. Accept the flat shape defensively too.
+                            const candidate = record;
+                            if (candidate === null || typeof candidate !== 'object')
+                                continue;
+                            const inner = typeof candidate.event === 'object' && candidate.event !== null
+                                ? candidate.event
+                                : candidate;
+                            if (typeof inner.type !== 'string')
+                                continue;
+                            if (typeof inner.seq === 'number') {
+                                if (inner.seq <= through)
+                                    continue;
+                                if (inner.seq > delivered)
+                                    delivered = inner.seq;
+                            }
+                            if (process.env['DSH_DISCORD_TRACE'] === '1') {
+                                // Full data dump (truncated): diagnosis needs the field
+                                // shapes, not just the key names — keys hide nesting.
+                                const dumped = JSON.stringify(inner.data);
+                                console.error(`[dsh-discord:trace] record type=${inner.type} seq=${String(inner.seq)} data=${dumped.length > 800 ? `${dumped.slice(0, 800)}…` : dumped}`);
+                            }
+                            consumer?.push({
+                                type: 'session/event',
+                                sessionId,
+                                event: { type: inner.type, data: (typeof inner.data === 'object' && inner.data !== null ? inner.data : {}) },
+                            });
+                        }
+                        if (delivered > through)
+                            watermark.set(sessionId, delivered);
+                    }
+                    else if (frame['type'] === 'assistant-stream') {
+                        // Live assistant deltas ride the dedicated stream frames; the
+                        // renderer's durable events already carry the message texts.
+                        if (process.env['DSH_DISCORD_TRACE'] === '1') {
+                            const dumped = JSON.stringify(frame);
+                            console.error(`[dsh-discord:trace] assistant-stream frame=${dumped.length > 300 ? `${dumped.slice(0, 300)}…` : dumped}`);
+                        }
+                        continue;
+                    }
+                    else if (process.env['DSH_DISCORD_TRACE'] === '1') {
+                        const dumped = JSON.stringify(frame);
+                        console.error(`[dsh-discord:trace] follow-frame UNHANDLED type=${String(frame['type'])} frame=${dumped.length > 400 ? `${dumped.slice(0, 400)}…` : dumped}`);
+                    }
+                }
+            }
+            catch (cause) {
+                if (!per.signal.aborted) {
+                    if (process.env['DSH_DISCORD_TRACE'] === '1')
+                        console.error(`[dsh-discord:trace] follow-threw session=${sessionId.slice(0, 8)} cause=${String(cause).slice(0, 300)}`);
+                    log?.('discord_host_follow_threw', { sessionId, cause: String(cause) });
+                }
+            }
+            finally {
+                if (process.env['DSH_DISCORD_TRACE'] === '1')
+                    console.error(`[dsh-discord:trace] follow-end session=${sessionId.slice(0, 8)} aborted=${String(per.signal.aborted)} tracked=${String(tracked.get(sessionId) === per)}`);
+                if (tracked.get(sessionId) === per)
+                    tracked.delete(sessionId);
+                // A follow stream may END normally once its snapshot is delivered
+                // (a cold session has no live agent to follow): without a
+                // re-subscribe, every later turn is invisible until the next
+                // process restart replays the journal. Re-arm with backoff.
+                if (!per.signal.aborted) {
+                    const delayMs = Math.min(30_000, 1_000 * 2 ** attempt);
+                    setTimeout(() => {
+                        if (!per.signal.aborted && !tracked.has(sessionId)) {
+                            log?.('discord_host_follow_resubscribed', { sessionId, delayMs });
+                            startLoop(sessionId, attempt + 1);
+                        }
+                    }, delayMs);
+                }
+            }
+        })();
+    };
+    const startControlLoop = (signal) => {
+        void (async () => {
+            try {
+                for await (const raw of services.control(signal)) {
+                    if (!isRecord(raw))
+                        continue;
+                    const frame = raw;
+                    if (process.env['DSH_DISCORD_TRACE'] === '1') {
+                        const dumped = JSON.stringify(frame);
+                        console.error(`[dsh-discord:trace] control type=${String(frame['type'])} frame=${dumped.length > 400 ? `${dumped.slice(0, 400)}…` : dumped}`);
+                    }
+                    if (frame['type'] === 'queue' && typeof frame['sessionId'] === 'string') {
+                        const rawItems = Array.isArray(frame['items']) ? frame['items'] : [];
+                        const items = rawItems
+                            .filter((item) => isRecord(item) && typeof item['id'] === 'string')
+                            .map(item => ({
+                            id: item['id'],
+                            summary: queueItemSummary(isRecord(item['message']) ? item['message']['content'] : undefined),
+                        }));
+                        consumer?.push({
+                            type: 'session/queue',
+                            sessionId: frame['sessionId'],
+                            items,
+                        });
+                    }
+                    // baseline / jobs / projection frames carry no live-render state.
+                }
+            }
+            catch (cause) {
+                if (!signal.aborted) {
+                    log?.('discord_host_control_threw', { cause: String(cause) });
+                }
+            }
+        })();
+    };
+    return {
+        track(sessionId) {
+            if (sessionId === '' || tracked.has(sessionId))
+                return;
+            if (rootSignal?.aborted)
+                return;
+            startLoop(sessionId);
+        },
+        stream(signal) {
+            if (process.env['DSH_DISCORD_TRACE'] === '1')
+                console.error(`[dsh-discord:trace] router-stream-open tracked=${String(tracked.size)} rearm=${String(tracked.size)}`);
+            rootSignal = signal;
+            const queue = createFrameQueue();
+            consumer = queue;
+            // Re-arm every already-tracked session against the new consumer.
+            for (const [sessionId, per] of [...tracked.entries()]) {
+                per.abort();
+                tracked.delete(sessionId);
+                startLoop(sessionId);
+            }
+            startControlLoop(signal);
+            return queue.iterate(signal);
+        },
+    };
+}

package/lib/dsh/host-face.d.ts

@@ -0,0 +1,418 @@
+/**
+ * The typed防腐层 over the Host's 0.1.6 controller services — the cordis
+ * services `sessionController`, `workspaceController`, and `sessionQuery`
+ * that replaced the 0.1.1-rc.2 `apiProxy` gateway. Domain methods speak the
+ * typert faces directly: plain request objects in, plain values out, and
+ * business rejections carried as thrown `RemoteError`s (`{code, message}`).
+ * Two guarantees are preserved from the rc.2 seam:
+ *
+ * 1. Boundedness — a Host that never answers must not wedge an interaction
+ *    handler (or a Discord ephemeral) forever; every call races a timeout and
+ *    resolves to an unobservable outcome instead.
+ * 2. Observability — every terminal outcome is reported through the injected
+ *    log sink, so a silent-void call can never again be misread as a hang.
+ *
+ * The exported port-level API (function names, outcome unions) is unchanged
+ * from the rc.2 face: the Discord features and their tests keep their
+ * vocabulary while this module alone absorbs the host-side rebase.
+ */
+import type { ProjectListPort } from '../features/project-list.js';
+import type { WorkspaceResolver } from '../features/project-bind.js';
+import type { DshModelPort } from '../features/model-control.js';
+/** The workspace rows the catalog port needs (subset of WorkspaceView). */
+export interface WorkspaceCatalogEntry {
+    workspaceId: string;
+    title: string;
+    /** Canonical directory; present in Host responses, rendered only to proven administrators. */
+    path?: string | undefined;
+}
+/**
+ * Narrow slice of the 0.1.6 `sessionController` cordis service. Method
+ * shapes mirror the typert descriptors in @deepseek-ai/dsh-api-session-controller.
+ */
+export interface DshSessionControllerFace {
+    prompt(request: {
+        requestId: string;
+        sessionId: string;
+        mode: 'queue' | 'steer';
+        content: Array<{
+            type: 'text';
+            text: string;
+        } | {
+            type: 'image';
+            mediaType: string;
+            data: string;
+        }>;
+        clientTimeZone?: string;
+    }, signal: AbortSignal): Promise<{
+        accepted: true;
+    }>;
+    create(request: {
+        workspaceId?: string;
+        cwd?: string;
+        sessionId?: string;
+        agentPreset?: string;
+    }): Promise<{
+        sessionId: string;
+        agentPreset?: string;
+    }>;
+    /** The durable Session list; the host takes ONLY an optional cancellation signal. */
+    list(signal: AbortSignal | undefined): Promise<{
+        items: unknown[];
+    }>;
+    cancel(request: {
+        sessionId: string;
+    }): Promise<{
+        accepted: true;
+    }>;
+    updateQueue(request: {
+        sessionId: string;
+        itemId: string;
+        action: {
+            kind: 'remove';
+        };
+    }): Promise<{
+        accepted: true;
+    }>;
+    selectModel(request: {
+        sessionId: string;
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    }): Promise<{
+        selected: ModelSelectionShape;
+    }>;
+    modelCatalog(): Promise<ModelCatalogWireShape>;
+    /** Per-session durable journal stream (live frames after one opening snapshot). */
+    follow(request: {
+        address: {
+            kind: 'session';
+            sessionId: string;
+        };
+        assistantStream?: true;
+    }, signal: AbortSignal): AsyncIterable<unknown>;
+    /** Host-wide live state stream (queue/jobs/projection frames over one baseline). */
+    control(signal: AbortSignal): AsyncIterable<unknown>;
+}
+/**
+ * Narrow slice of the 0.1.6 `workspaceController` cordis service. The
+ * registry baseline (`baseline()`) is the synchronous successor of the rc.2
+ * unary `workspace.list` RPC.
+ */
+export interface DshWorkspaceControllerFace {
+    /** Workspace state stream; every generation starts with exactly one baseline frame. */
+    follow(signal: AbortSignal): AsyncIterable<unknown>;
+}
+/**
+ * Narrow slice of `sessionQuery` — the per-session projection read the /model
+ * surface needs for the session's live selection (the rc.2 `sessions.models`
+ * RPC split into the global `modelCatalog` plus this projection).
+ */
+export interface DshSessionQueryFace {
+    observeSession(sessionId: string): Promise<{
+        header?: {
+            cwd?: string;
+        };
+        projections?: {
+            values?: Record<string, unknown>;
+        };
+    } & Partial<AsyncDisposable>>;
+}
+/** The host-generation model catalog (`session/modelCatalog`, host-wide). */
+export interface ModelCatalogWireShape {
+    default: ModelSelectionShape;
+    routableProviders: string[];
+    groups: ModelProviderGroupShape[];
+    failures: Array<{
+        id: string;
+        name: string;
+        message: string;
+    }>;
+}
+/** The composite host face every port factory in this module consumes. */
+export interface DshHostFace {
+    session: DshSessionControllerFace;
+    workspace: DshWorkspaceControllerFace;
+    sessionQuery: DshSessionQueryFace;
+}
+/**
+ * Resolve the 0.1.6 controller services off the Cordis context. Throws one
+ * actionable TypeError naming every absent service — the composition root
+ * treats that as a fail-loud startup boundary, never a silent half-mount.
+ */
+export declare function resolveHostFace(ctx: {
+    get(name: string): unknown;
+}): DshHostFace;
+/** Defensive read of the title projection in a list row's values. */
+export interface SessionProjectionsShape {
+    values?: {
+        title?: unknown;
+    };
+}
+/** The per-session summary `session.list` returns (rich rows, untrusted wire). */
+export interface SessionSummaryShape {
+    sessionId: string;
+    updatedAt: number;
+    running: boolean;
+    blank: boolean;
+    cwd?: string;
+    agentPreset?: string;
+    origin?: 'subagent';
+    projections?: SessionProjectionsShape;
+}
+/** The complete provider/model/reasoning selection (dsh-agent ModelSelection). */
+export interface ModelSelectionShape {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** One reasoning effort a model's adapter advertises (sessions.d.ts). */
+export interface ModelReasoningEffortShape {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** Exact-route reasoning metadata for one catalog model. */
+export interface ModelReasoningShape {
+    efforts: ModelReasoningEffortShape[];
+    defaultEffort?: string;
+}
+/** One model inside a provider group (sessions.d.ts ModelCatalogModel). */
+export interface ModelCatalogModelShape {
+    id: string;
+    name: string;
+    description?: string;
+    reasoning?: ModelReasoningShape;
+}
+/** One provider group and its models (sessions.d.ts ModelProviderGroup). */
+export interface ModelProviderGroupShape {
+    id: string;
+    name: string;
+    models: ModelCatalogModelShape[];
+}
+/**
+ * The detached model directory the /model cascade browses (port shape,
+ * unchanged from rc.2): the session's live selection, whether its route
+ * still serves, and the per-provider catalog groups.
+ */
+export interface SessionModelsShape {
+    current: ModelSelectionShape;
+    routable: boolean;
+    groups: ModelProviderGroupShape[];
+    failures: Array<{
+        id: string;
+        name: string;
+        message: string;
+    }>;
+}
+/** Raised when the Host did not answer within the bounded window. */
+export declare class RpcTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/** Race one host promise against a bounded window. */
+export declare function withRpcTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+/** Diagnostic sink shared by every face function. */
+export type ApiProxyLog = (event: string, detail?: unknown) => void;
+export interface ApiProxyFaceOptions {
+    timeoutMs?: number;
+    log?: ApiProxyLog;
+}
+/**
+ * The bind flow's catalog verifier: resolves an opaque `ws:` reference
+ * against the live workspace baseline. A well-formed reference the registry
+ * no longer knows — and any malformed one — resolve `stale` (fail-closed, no
+ * write can follow); a Host error is `failed`; a timeout is `unknown`.
+ */
+export declare function createWorkspaceResolver(dsh: DshHostFace, options?: ApiProxyFaceOptions): WorkspaceResolver;
+/**
+ * The `/project list` catalog port over the workspace registry baseline.
+ * Outcomes follow the port contract: a definitive Host error is `failed`
+ * (sanitized before Discord), while a timeout or unreadable body is
+ * `unknown` — delivery was not observed, so no retry is implied.
+ */
+export declare function createWorkspaceCatalogPort(dsh: DshHostFace, options?: ApiProxyFaceOptions): ProjectListPort;
+export type WorkspaceDetailOutcome = {
+    outcome: 'found';
+    workspace: {
+        id: string;
+        title: string;
+        path: string | undefined;
+    };
+} | {
+    outcome: 'stale';
+} | {
+    outcome: 'failed';
+} | {
+    outcome: 'unknown';
+};
+/**
+ * Read one Workspace's full view (title plus canonical path). The path is
+ * for the administrator-only ephemeral info response — the disclosure
+ * policy owns whether it ever renders; this face only carries it in memory.
+ */
+export declare function readWorkspaceDetail(dsh: DshHostFace, reference: string, options?: ApiProxyFaceOptions): Promise<WorkspaceDetailOutcome>;
+export type PromptOutcome = {
+    outcome: 'accepted';
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/**
+ * Submit one prompt turn through the session controller. A definitive Host
+ * rejection (thrown RemoteError) is a rejection carrying the sanitized
+ * reason; a timeout or host fault is `unknown` — the turn may or may not
+ * have been admitted, so callers must not resubmit. `options.rpcId` pins
+ * the adapter-owned stable request id, which the Host records on the
+ * durable user message (`source.rpcId`) and de-duplicates on — the 0.1.6
+ * admission layer replays `{accepted: true}` for a repeated id, keeping the
+ * at-most-once discipline observable. Images (16.50) encode as ordered
+ * `image` parts after the text part.
+ */
+export declare function promptSession(dsh: DshHostFace, request: {
+    sessionId: string;
+    prompt: string;
+    images?: ReadonlyArray<{
+        mediaType: string;
+        base64: string;
+    }>;
+}, options?: ApiProxyFaceOptions & {
+    rpcId?: string;
+}): Promise<PromptOutcome>;
+/**
+ * Steer the session's active turn: `session.prompt` with `mode: 'steer'`,
+ * carrying the same stable request-id discipline as the queue path.
+ */
+export declare function steerSession(dsh: DshHostFace, request: {
+    sessionId: string;
+    prompt: string;
+}, options?: ApiProxyFaceOptions & {
+    rpcId?: string;
+}): Promise<PromptOutcome>;
+export type CreateSessionOutcome = {
+    outcome: 'completed';
+    sessionId: string;
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/**
+ * Create one DSH Session against a preallocated id (design.md §10): the 0.1.6
+ * controller adopts the same session id idempotently, so an uncertain
+ * response never forks a second Session. Same outcome discipline as the
+ * prompt path.
+ */
+export declare function createSessionViaProxy(dsh: DshHostFace, request: {
+    sessionId: string;
+    workspaceId: string;
+}, options?: ApiProxyFaceOptions): Promise<CreateSessionOutcome>;
+/** The durable Session-id baseline reconciliation reconciles against. */
+export type SessionIdListOutcome = {
+    outcome: 'completed';
+    ids: string[];
+} | {
+    outcome: 'failed';
+} | {
+    outcome: 'unknown';
+};
+/** List durable Session ids (`session.list` returns everything in one page). */
+export declare function listSessionIds(dsh: DshHostFace, options?: ApiProxyFaceOptions): Promise<SessionIdListOutcome>;
+/** A list row narrowed to what the /session resume surface renders. */
+export interface SessionResumeRow {
+    sessionId: string;
+    title: string | undefined;
+    updatedAt: number;
+    running: boolean;
+    blank: boolean;
+    cwd: string | undefined;
+    origin: 'subagent' | undefined;
+}
+export type SessionSummariesOutcome = {
+    outcome: 'completed';
+    sessions: SessionResumeRow[];
+} | {
+    outcome: 'failed';
+} | {
+    outcome: 'unknown';
+};
+/**
+ * The rich `session.list` for the /session resume surface: titles ride each
+ * row's projection values (absence = the session has no title yet), blank
+ * sessions are flagged, and rows arrive updatedAt-descending. Defensive
+ * narrowing: the wire is untrusted, extra/missing fields never throw.
+ */
+export declare function listSessionSummaries(dsh: DshHostFace, options?: ApiProxyFaceOptions): Promise<SessionSummariesOutcome>;
+export type CancelOutcome = {
+    outcome: 'accepted';
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/** Cancel the session's active turn (`session.cancel`); DSH preserves the pending inbox. */
+export declare function cancelSessionViaProxy(dsh: DshHostFace, request: {
+    sessionId: string;
+}, options?: ApiProxyFaceOptions): Promise<CancelOutcome>;
+export type QueueRemoveOutcome = {
+    outcome: 'accepted';
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/** Remove one pending inbox item (`session.updateQueue`, action remove). */
+export declare function removeQueueItemViaProxy(dsh: DshHostFace, request: {
+    sessionId: string;
+    itemId: string;
+}, options?: ApiProxyFaceOptions): Promise<QueueRemoveOutcome>;
+export type SessionModelsOutcome = {
+    outcome: 'completed';
+    models: SessionModelsShape;
+} | {
+    outcome: 'failed';
+} | {
+    outcome: 'unknown';
+};
+/**
+ * The session's detached model directory: the live selection, whether its
+ * route still serves, and the per-provider catalog groups the /model
+ * cascade browses. Composed from the 0.1.6 global `modelCatalog` plus the
+ * session's `modelSelection` projection — the rc.2 per-session
+ * `sessions.models` RPC no longer exists.
+ */
+export declare function sessionModels(dsh: DshHostFace, request: {
+    sessionId: string;
+}, options?: ApiProxyFaceOptions): Promise<SessionModelsOutcome>;
+export type SelectModelOutcome = {
+    outcome: 'completed';
+    selected: ModelSelectionShape;
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/**
+ * Select the complete model selection for one session (session.selectModel):
+ * the session switches immediately and the Host records the choice as the
+ * default for sessions that have not logged their own — the response only
+ * proves the session switch, so callers must not claim the persistence
+ * outcome (design.md §7).
+ */
+export declare function selectSessionModel(dsh: DshHostFace, request: {
+    sessionId: string;
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}, options?: ApiProxyFaceOptions): Promise<SelectModelOutcome>;
+/**
+ * The /model surface over the session controller: the composed per-session
+ * directory and the guarded selection mutation — the shapes model-control
+ * reasons about.
+ */
+export declare function createModelPort(dsh: DshHostFace, options?: ApiProxyFaceOptions): DshModelPort;