@yadsh/dsh-qa-surface 0.1.1 → 0.2.0

package/lib/types/client/QaSessionController.d.ts

@@ -1,59 +1,146 @@
-import type { HostDescriptionSource, IApiClient } from "@deepseek-ai/dsh-client-connection/client";
-import type { ISessions, SessionListState } from "@deepseek-ai/dsh-client-runtime/client";
-import type { QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
-type QaSessionsApi = Pick<IApiClient["sessions"], "create" | "selectModel">;
-export interface StorageLike {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-}
+import type { HostDescriptionSource } from "@deepseek-ai/dsh-client-connection/client";
+import type { QaImageDraft, QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaSecureSession, QaSessions, QaSessionsApi, StorageLike } from "./types.js";
 export interface QaSessionControllerOptions {
-    readonly sessions: ISessions;
+    readonly sessions: QaSessions;
     readonly api: QaSessionsApi;
     readonly connection: HostDescriptionSource;
     readonly config: ResolvedQaSurfaceConfig;
+    readonly secureSession: QaSecureSession;
     readonly storage?: StorageLike;
     readonly timeoutMs?: number;
+    /**
+     * Minimum spacing between projections of a running turn's stream frames.
+     * The host runtime already batches deltas to one notification per
+     * animation frame; this ceiling keeps the render path flat on long
+     * transcripts and weak hardware. Zero disables the spacing.
+     */
+    readonly streamIntervalMs?: number;
 }
-/** The only module that couples QA behavior to DSH Session/client APIs. */
+/**
+ * The only module that couples QA behavior to DSH Session/client APIs. It owns
+ * the chat lifecycle state machine; the observable wait, browser-local chat
+ * bookkeeping and policy-attestation details live in their own modules.
+ */
 export declare class QaSessionController {
     private readonly listeners;
     private readonly sessions;
     private readonly api;
     private readonly connection;
     private readonly config;
-    private readonly storage;
+    private readonly secureSessionRemote;
+    private readonly chats;
     private readonly timeoutMs;
+    private readonly streamIntervalMs;
     private state;
     private session;
     private unsubscribeSession;
     private readonly unsubscribeConnection;
     private ensuring;
+    private materializing;
     private operationError;
     private admissionPending;
+    private policyReady;
+    private drafting;
+    private streamFlushTimer;
+    /** The chat session to return to when a subagent view closes. */
+    private chatSessionId;
+    private viewingSubagent;
     private connectedOnce;
     private disposed;
     private generation;
+    private chatsRevision;
     constructor(options: QaSessionControllerOptions);
     getSnapshot: () => QaSessionState;
     subscribe: (listener: () => void) => (() => void);
     ensureSession(): Promise<void>;
-    send(text: string): Promise<boolean>;
+    send(text: string, images?: readonly QaImageDraft[]): Promise<boolean>;
+    /**
+     * Ask for a fresh variant of the previous answer. The session has no
+     * truncation seam, so this sends the hidden regeneration instruction as an
+     * ordinary prompt: the model produces a follow-up turn, the projection
+     * hides the marker message, and the consecutive turns read as variants of
+     * the original question (switched in the surface).
+     */
+    regenerate(): Promise<boolean>;
     stop(): Promise<void>;
-    reset(): Promise<void>;
+    /**
+     * Enter the "new chat" draft: show an empty composer without creating any
+     * session. Nothing appears in the chat list and no Host session is spent
+     * until the first prompt is actually sent, which materializes the session
+     * lazily ({@link materializeDraft}). Fixed-policy deployments cannot draft.
+     */
+    startDraft(): Promise<void>;
+    /**
+     * Turn the current draft into a real attested session. Runs inside the
+     * send flow; concurrent sends share one materialization. A refusal here is
+     * reported at once — a fresh session's first attestation is the
+     * deployment's only chance to learn the reason.
+     */
+    private materializeDraft;
+    /**
+     * Open one of this browser's indexed chats. The id must be present in the
+     * host session list and pass policy attestation; an unknown id is forgotten
+     * from the index. Fixed-policy deployments cannot switch.
+     */
+    switchTo(sessionId: string): Promise<void>;
+    /**
+     * Watch a subagent's transcript live. The binding is read-only by
+     * construction: no attestation runs (attestation admits sending, and the
+     * composer stays disabled here), the chat index is untouched, and
+     * {@link closeSubagent} returns to the chat the panel was opened from.
+     */
+    viewSubagent(id: string, title: string): Promise<void>;
+    /** Leave the subagent transcript and re-open the chat it was launched from. */
+    closeSubagent(): Promise<void>;
+    /** This browser's indexed chat ids, most recently used first. */
+    chatIds(): readonly string[];
+    /** The bound session id, or null while no chat is bound. */
+    activeSessionId(): string | null;
+    /**
+     * Resolve one durable image attachment of the bound session into a
+     * browser-usable URL. The caller caches; failures surface as broken views.
+     */
+    readImage(attachmentId: string): Promise<string>;
+    /**
+     * Remove one chat from this browser's index. Deleting the chat that is
+     * currently open also forgets the persisted id and starts a fresh attested
+     * session (when the deployment allows session resets); the Host-side
+     * session itself is not touched — no host deletion seam exists.
+     */
+    deleteChat(id: string): Promise<void>;
+    /** Drop one chat id from this browser's index. */
+    forgetChat(sessionId: string): void;
     dispose(): void;
     private ensureSessionNow;
+    /**
+     * Recovery ladder after a refused send-time attestation. The prompt was
+     * never admitted, so nothing here can duplicate it. Step 1 re-opens the
+     * session: a Host that idled the agent out dismantles its tool view, and
+     * re-opening re-materializes it. Step 2 — when that refused session is
+     * still blank (it never received the prompt, so there is nothing to lose) —
+     * starts a fresh attested session instead. A session with history is left
+     * alone: recreating it would silently drop the conversation.
+     */
+    private recoverForSend;
     private createSession;
     private bind;
     private unbind;
     private waitForConnection;
+    /**
+     * Project one session notification. A running turn's frames arrive at
+     * animation-frame cadence, so re-projections are spaced at least
+     * {@link streamIntervalMs} apart: the first frame of a window projects at
+     * once and further frames are absorbed (the memoized render path replays
+     * nothing, so absorbing a frame only defers it). Everything outside a
+     * running turn - phase flips, errors, turn completion - projects
+     * immediately.
+     */
+    private publishSessionUpdate;
+    private clearStreamFlush;
     private publish;
     private fail;
-    private storageKey;
-    private readPersisted;
-    private persist;
-    private clearPersisted;
+    private attestPolicy;
     private emit;
 }
-export type { SessionListState };
 //# sourceMappingURL=QaSessionController.d.ts.map

package/lib/types/client/QaSurface.d.ts

@@ -1,14 +1,15 @@
-import type { HostDescriptionSource, IApiClient } from "@deepseek-ai/dsh-client-connection/client";
-import type { ISessions } from "@deepseek-ai/dsh-client-runtime/client";
+import type { HostDescriptionSource } from "@deepseek-ai/dsh-client-connection/client";
 import type { InjectFace, PropsRuntime } from "@deepseek-ai/dsh-client-ui-slots";
 import type { QaConfigController } from "./QaConfigController.js";
 import type { QaRouteController } from "./QaRouteController.js";
+import type { QaSecureSession, QaSessions, QaSessionsApi } from "./types.js";
 export interface QaSurfaceFace {
     readonly route: QaRouteController;
     readonly config: QaConfigController;
-    readonly sessions: ISessions;
-    readonly api: Pick<IApiClient["sessions"], "create" | "selectModel">;
+    readonly sessions: QaSessions;
+    readonly api: QaSessionsApi;
     readonly connection: HostDescriptionSource;
+    readonly secureSession: QaSecureSession;
 }
 type QaSurfaceProps = PropsRuntime<"shell.overlay"> & InjectFace<QaSurfaceFace>;
 export declare function QaSurface(props: QaSurfaceProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/types/client/QaTranscriptAdapter.d.ts

@@ -1,7 +1,22 @@
 import type { ConversationSnapshot } from "@deepseek-ai/dsh-client-runtime/client";
-import type { QaMessage } from "../types.js";
-/** Project only end-user-safe text from the public DSH conversation snapshot. */
+import type { QaMessage, QaSource } from "../types.js";
+/**
+ * The hidden regeneration prompt. Regenerate sends this as an ordinary
+ * prompt — the session has no truncation seam, so a "variant" is a real
+ * follow-up turn — and the projection drops it from the visible transcript,
+ * leaving the consecutive answer turns to read as variants of one question.
+ */
+export declare const QA_REGENERATE_MARKER = "\u041F\u0435\u0440\u0435\u0433\u0435\u043D\u0435\u0440\u0438\u0440\u0443\u0439 \u0441\u0432\u043E\u0439 \u043F\u0440\u0435\u0434\u044B\u0434\u0443\u0449\u0438\u0439 \u043E\u0442\u0432\u0435\u0442 \u2014 \u0434\u0430\u0439 \u043D\u043E\u0432\u044B\u0439 \u0432\u0430\u0440\u0438\u0430\u043D\u0442, \u043D\u0435 \u043F\u043E\u0432\u0442\u043E\u0440\u044F\u044F \u043F\u0440\u0435\u0434\u044B\u0434\u0443\u0449\u0438\u0439.";
+/** Project end-user messages plus optional operator-approved work detail. */
 export declare function projectTranscript(snapshot: ConversationSnapshot, options?: {
     readonly showToolActivity?: boolean;
+    readonly showReasoning?: boolean;
 }): readonly QaMessage[];
+/**
+ * Collect the sources this chat has actually touched, in first-use order:
+ * fetched pages, searches, and files read. This is the same tool activity the
+ * work groups render, projected as a flat citation-style list, so it carries
+ * no information beyond `ui.showToolActivity`.
+ */
+export declare function projectSources(snapshot: ConversationSnapshot): readonly QaSource[];
 //# sourceMappingURL=QaTranscriptAdapter.d.ts.map

package/lib/types/client/attestation.d.ts

@@ -0,0 +1,25 @@
+import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "../types.js";
+/**
+ * Browser-side reading of Host policy attestation: one error type the session
+ * lifecycle branches on, plus pure diagnostics for the console. The specific
+ * mismatch facts stay in the Host logs; a refusal only reveals the coarse
+ * reason class and an operator hint.
+ */
+export declare class QaPolicyAttestationError extends Error {
+    constructor();
+}
+/**
+ * Extract the coarse attestation reason code from a Host wire failure, if the
+ * failure carries the marker.
+ */
+export declare function attestationReasonOf(failure: {
+    readonly message?: string;
+} | undefined | null): string | null;
+export declare function attestationHint(reason: string | null): string;
+/**
+ * Whether a Host proof answers the deployment lockdown config this browser
+ * holds. Every field must match; the allow-list is compared as exact JSON so
+ * order differences refuse too, mirroring the Host's pinned list.
+ */
+export declare function proofMatchesConfig(proof: QaLockdownProof, lockdown: ResolvedQaSurfaceConfig["lockdown"], sessionId: string): boolean;
+//# sourceMappingURL=attestation.d.ts.map

package/lib/types/client/chat-index.d.ts

@@ -0,0 +1,28 @@
+import type { StorageLike } from "./types.js";
+/**
+ * Browser-local chat bookkeeping: a most-recently-used index of chat ids for
+ * the sidebar plus the id of the chat this browser reopens on load. Both live
+ * under the deployment's storage key and route path, and every access
+ * tolerates a denied or broken store — persistence must never prevent a real
+ * DSH session.
+ */
+export declare class QaChatIndex {
+    private readonly storage;
+    private readonly sessionKey;
+    private readonly chatKey;
+    constructor(storage: StorageLike | undefined, prefix: string);
+    /** This browser's indexed chat ids, most recently used first. */
+    chatIds(): readonly string[];
+    /**
+     * Add one chat to the index without reordering anything. Display order is
+     * the host's `updatedAt`, so merely opening a chat must not move it — the
+     * index is membership only.
+     */
+    addChat(sessionId: string): void;
+    forgetChat(sessionId: string): void;
+    /** The persisted chat id this browser reopens on load, or null. */
+    activeId(): string | null;
+    saveActive(sessionId: string): void;
+    clearActive(): void;
+}
+//# sourceMappingURL=chat-index.d.ts.map

package/lib/types/client/components/Markdown.d.ts

@@ -1,5 +1,9 @@
-/** Deliberately small, HTML-free Markdown renderer for assistant-visible text. */
-export declare function Markdown({ text }: {
+/**
+ * Deliberately small, HTML-free Markdown renderer for assistant-visible text.
+ * Memoized on the text value: stream updates re-render only the message whose
+ * text actually changed, so committed history is never re-parsed.
+ */
+export declare const Markdown: import("react").MemoExoticComponent<({ text, }: {
     readonly text: string;
-}): import("react/jsx-runtime").JSX.Element;
+}) => import("react/jsx-runtime").JSX.Element>;
 //# sourceMappingURL=Markdown.d.ts.map

package/lib/types/client/components/QaAgentsDrawer.d.ts

@@ -0,0 +1,25 @@
+import type { SessionSummary } from "@deepseek-ai/dsh-client-runtime/client";
+/** One row of the agents panel: a subagent session of the open chat. */
+export interface QaSubagentRow {
+    readonly id: string;
+    readonly title: string;
+    readonly running: boolean;
+    readonly completed: boolean;
+    readonly meta: string;
+}
+/**
+ * Direct subagent children of the open chat, running first. Reads the host
+ * session list's lineage (parentId + origin), so no extra subscription beyond
+ * the list the surface already follows.
+ */
+export declare function collectSubagents(byId: Readonly<Record<string, SessionSummary>>, rootId: string | null, now?: number): readonly QaSubagentRow[];
+export interface QaAgentsDrawerProps {
+    readonly agents: readonly QaSubagentRow[];
+    /** The subagent currently watched, if any. */
+    readonly activeId: string | null;
+    readonly onView: (id: string, title: string) => void;
+    readonly onClose: () => void;
+}
+/** Right-hand panel listing the chat's subagents. */
+export declare function QaAgentsDrawer({ agents, activeId, onView, onClose, }: QaAgentsDrawerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=QaAgentsDrawer.d.ts.map

package/lib/types/client/components/QaComposer.d.ts

@@ -1,11 +1,21 @@
+import type { QaImageDraft } from "../../types.js";
 export interface QaComposerProps {
     readonly placeholder: string;
+    readonly quickQuestions?: readonly string[];
     readonly canSend: boolean;
     readonly canStop: boolean;
     readonly running: boolean;
     readonly showStop: boolean;
-    readonly onSend: (text: string) => Promise<boolean>;
+    readonly status: string | null;
+    readonly images: readonly QaImageDraft[];
+    readonly onImagesChange: (images: readonly QaImageDraft[]) => void;
+    readonly onSend: (text: string, images: readonly QaImageDraft[]) => Promise<boolean>;
     readonly onStop: () => Promise<void>;
 }
-export declare function QaComposer(props: QaComposerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Memoized with the default shallow compare: every prop is a scalar, a
+ * stable array or a stable callback, so a stream of transcript frames never
+ * re-renders the composer and typing stays responsive while an answer runs.
+ */
+export declare const QaComposer: import("react").MemoExoticComponent<(props: QaComposerProps) => import("react/jsx-runtime").JSX.Element>;
 //# sourceMappingURL=QaComposer.d.ts.map

package/lib/types/client/components/QaMessage.d.ts

@@ -3,6 +3,19 @@ export interface QaMessageProps {
     readonly message: QaMessageModel;
     readonly renderMarkdown: boolean;
     readonly showTimestamp: boolean;
+    /** Storage prefix persisted message ratings live under. */
+    readonly stateKey?: string;
+    /** Ask for a fresh variant of this answer; omit to hide the control. */
+    readonly onRegenerate?: () => void;
+    /** Resolve one durable attachment into a viewable URL. */
+    readonly resolveImage?: (attachmentId: string) => Promise<string>;
 }
-export declare function QaMessage({ message, renderMarkdown, showTimestamp, }: QaMessageProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Whether two transcript messages render identically. The transcript
+ * projection rebuilds every message object on each published frame, so the
+ * memoized row compares rendered content instead of references; string
+ * comparison is by value, which keeps fresh copies cheap to recognize.
+ */
+export declare function sameMessage(a: QaMessageModel, b: QaMessageModel): boolean;
+export declare const QaMessage: import("react").MemoExoticComponent<({ message, renderMarkdown, showTimestamp, stateKey, onRegenerate, resolveImage, }: QaMessageProps) => import("react/jsx-runtime").JSX.Element>;
 //# sourceMappingURL=QaMessage.d.ts.map

package/lib/types/client/components/QaSidebar.d.ts

@@ -0,0 +1,41 @@
+import type { SessionSummary } from "@deepseek-ai/dsh-client-runtime/client";
+/** One renderable row of the chat-history sidebar. */
+export interface QaChatRow {
+    readonly id: string;
+    readonly title: string;
+    readonly running: boolean;
+    readonly active: boolean;
+    readonly meta: string;
+    readonly updatedAt: number;
+}
+/**
+ * Project this browser's indexed chat ids onto the host session list, most
+ * recently updated first. Opening a chat is not an update: only the host's
+ * `updatedAt` (fresh messages) orders the list. Ids the host no longer lists
+ * are skipped (the controller prunes them on switch).
+ */
+export declare function buildChatRows(chatIds: readonly string[], byId: Readonly<Record<string, SessionSummary>>, activeId: string | null, now?: number): readonly QaChatRow[];
+export interface QaSidebarProps {
+    readonly rows: readonly QaChatRow[];
+    /** Deployment brand shown next to the logo (also while collapsed). */
+    readonly title: string;
+    /** Optional image logo; a built-in mark is drawn when null. */
+    readonly logoUrl: string | null;
+    /** Storage prefix used to remember the collapsed state across reloads. */
+    readonly stateKey: string;
+    readonly showNewChat: boolean;
+    readonly busy: boolean;
+    readonly onSwitch: (sessionId: string) => void;
+    readonly onNewChat: () => void;
+    /** Removes a chat from this browser's index; omit to hide the control. */
+    readonly onDelete?: (sessionId: string) => void;
+}
+/**
+ * Whether two sidebar row lists show the same thing. Rows are rebuilt on
+ * every surface render (relative timestamps drift), so the memoized sidebar
+ * compares by content and skips frames that only move the transcript.
+ */
+export declare function sameChatRows(a: readonly QaChatRow[], b: readonly QaChatRow[]): boolean;
+/** The per-browser chat history shown beside the QA conversation. */
+export declare const QaSidebar: import("react").MemoExoticComponent<(props: QaSidebarProps) => import("react/jsx-runtime").JSX.Element>;
+//# sourceMappingURL=QaSidebar.d.ts.map

package/lib/types/client/components/QaSourcesDrawer.d.ts

@@ -0,0 +1,8 @@
+import type { QaSource } from "../../types.js";
+export interface QaSourcesDrawerProps {
+    readonly sources: readonly QaSource[];
+    readonly onClose: () => void;
+}
+/** Right-hand panel listing tool-derived sources with a detail pane. */
+export declare function QaSourcesDrawer({ sources, onClose }: QaSourcesDrawerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=QaSourcesDrawer.d.ts.map

package/lib/types/client/components/QaWorkGroup.d.ts

@@ -0,0 +1,19 @@
+import type { QaWorkItem } from "../../types.js";
+export interface QaWorkGroupProps {
+    readonly status: "running" | "complete";
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+    readonly items: readonly QaWorkItem[];
+    readonly renderMarkdown: boolean;
+}
+export declare const THINKING_PHRASES: readonly string[];
+/**
+ * Whether two work items render identically. The transcript projection
+ * rebuilds every item object on each published frame, so memoized work rows
+ * compare by rendered content instead of by reference.
+ */
+export declare function sameWorkItem(a: QaWorkItem, b: QaWorkItem): boolean;
+/** Whether two work item lists render identically, item for item. */
+export declare function sameWorkItems(a: readonly QaWorkItem[], b: readonly QaWorkItem[]): boolean;
+export declare const QaWorkGroup: import("react").MemoExoticComponent<({ status, startedAt, endedAt, items, renderMarkdown, }: QaWorkGroupProps) => import("react/jsx-runtime").JSX.Element>;
+//# sourceMappingURL=QaWorkGroup.d.ts.map

package/lib/types/client/components/VariantSwitcher.d.ts

@@ -0,0 +1,19 @@
+import type { QaMessage } from "../../types.js";
+export interface QaVariantGroup {
+    /** The user message that anchors the group. */
+    readonly groupId: string;
+    /** Answer turns triggered by that message, in order. */
+    readonly turns: readonly number[];
+}
+/**
+ * Group answer turns under the user message that triggered them. The session
+ * has no truncation seam, so a regenerated answer is a real follow-up turn;
+ * consecutive turns after one user message read as its variants.
+ */
+export declare function collectVariantGroups(messages: readonly QaMessage[]): readonly QaVariantGroup[];
+export declare function VariantSwitcher({ count, offset, onStep, }: {
+    readonly count: number;
+    readonly offset: number;
+    readonly onStep: (offset: number) => void;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=VariantSwitcher.d.ts.map

package/lib/types/client/components/format.d.ts

@@ -0,0 +1,9 @@
+/** Shared time formatting for the QA surface UI. */
+/** `только что`, `5 мин`, `3 ч`, `2 дн` or a ru-RU date past the week. */
+export declare function relativeTime(timestamp: number, now: number): string;
+/** `9 сент 15:44` - compact ru-RU day/month plus time. */
+export declare function formatDayTime(timestamp: number): string;
+/** `1,1 с` below ten seconds, `8 с` above. */
+export declare function formatSeconds(ms: number): string;
+export declare function formatWorkDuration(durationMs: number): string;
+//# sourceMappingURL=format.d.ts.map

package/lib/types/client/index.d.ts

@@ -1,17 +1,13 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { ConnectionHandle } from "@deepseek-ai/dsh-client-connection/client";
-import type { ISessions } from "@deepseek-ai/dsh-client-runtime/client";
-import type { SettingsScopeBinder } from "@deepseek-ai/dsh-client-ui-settings/client";
 declare module "@deepseek-ai/cordis" {
     interface Context {
         connection: ConnectionHandle;
-        sessions: ISessions;
-        settingsScope: SettingsScopeBinder;
     }
 }
 export declare const inject: string[];
 /** Register the route-aware, full-frame QA entry in the additive overlay slot. */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context): Promise<() => Promise<void>>;
 export { QaConfigController } from "./QaConfigController.js";
 export { QaRouteController, matchesQaRoute } from "./QaRouteController.js";
 export { QaSessionController } from "./QaSessionController.js";

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

@@ -0,0 +1,29 @@
+import type { IApiClient } from "@deepseek-ai/dsh-client-connection/client";
+import type { ISessions, SessionRuntime } from "@deepseek-ai/dsh-client-runtime/client";
+import type { QaLockdownProof, QaSessionState } from "../types.js";
+import type { SessionFace } from "@deepseek-ai/dsh-client-runtime/client";
+/** Wire content one prompt carries: text plus base64 image uploads. */
+export type QaPromptContent = Parameters<SessionFace["prompt"]>[0];
+/** DSH session runtime surface the QA controller is allowed to touch. */
+export type QaSessions = ISessions & Pick<SessionRuntime, "create">;
+/** Narrow client API slice used to pin the preset and model of a fresh chat. */
+export type QaSessionsApi = Pick<IApiClient["sessions"], "selectModel"> & {
+    readonly selectAgentPreset: IApiClient["agentPresets"]["select"];
+};
+/** Attestation channel to the Host admission boundary (`qaSurface/secureSession`). */
+export type QaSecureSession = (sessionId: string) => Promise<{
+    readonly ok: true;
+    readonly value: QaLockdownProof;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+}>;
+/** Minimal persistence contract; backed by `window.localStorage` in the app. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The state projected while no QA chat is bound (route inactive or booting). */
+export declare const QA_SESSION_IDLE_STATE: QaSessionState;
+//# sourceMappingURL=types.d.ts.map

package/lib/types/client/wait-for.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve with the first snapshot of an observable source that satisfies
+ * `predicate`, or reject after `timeoutMs`. This is the DSH-runtime glue the
+ * QA surface needs instead of ad-hoc sleeps; the source only has to expose
+ * the getSnapshot/subscribe store pair used across the client bundle.
+ */
+export declare function waitFor<T>(source: {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}, predicate: (value: T) => boolean, timeoutMs: number): Promise<T>;
+//# sourceMappingURL=wait-for.d.ts.map

package/lib/types/index.d.ts

@@ -1,7 +1,8 @@
-import { Service, type Context } from "@deepseek-ai/cordis";
-import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import type { Context } from "@deepseek-ai/cordis";
+import type { QaLockdownProof, QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
 export declare const name = "qa-surface";
-export declare const inject: readonly string[];
+export declare const inject: string[];
 export declare const QA_SURFACE_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
 export declare const Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
 declare module "@deepseek-ai/cordis" {
@@ -9,21 +10,36 @@ declare module "@deepseek-ai/cordis" {
         qaSurface: QaSurface;
     }
 }
-/** Small Host companion: validates config and exposes it through DSH settings. */
-export declare class QaSurface extends Service {
-    static inject: readonly string[];
+/** Host companion: validates config, owns the admission boundary and the route. */
+export declare class QaSurface extends TypertRemoteService {
+    static inject: string[];
     static Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
     private source;
     private readonly logger;
+    private readonly admission;
     private webServer;
     private disposeRoute;
     private routeKey;
     constructor(ctx: Context, entry?: QaSurfaceConfig);
     getConfig(): ResolvedQaSurfaceConfig;
+    /**
+     * Serve the effective QA configuration to the browser. The DSH gateway pins
+     * settings RPCs to loopback, so a browser served over the LAN always sees
+     * the settings namespace as unavailable; this method is the config channel
+     * such a browser falls back to. It is read-only projection — the admission
+     * boundary stays in {@link secureSession}.
+     */
+    describe(): ResolvedQaSurfaceConfig;
+    /** Pin and attest the effective policy. The browser supplies identity only. */
+    secureSession(sessionId: string): QaLockdownProof;
     private refreshRoute;
 }
 export { ConfigSchema, DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath, resolveConfig, } from "./config.js";
+export { QaAttestationError } from "./attestation.js";
+export type { QaAttestationReason } from "./attestation.js";
 export { registerQaNavigationRoute } from "./host-route.js";
+export { qaToolDenial, qaToolPolicyPlan } from "./lockdown-policy.js";
+export { QaPolicyAdmission } from "./secure-session.js";
 export type * from "./types.js";
 export default QaSurface;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/lockdown-policy.d.ts

@@ -0,0 +1,18 @@
+export interface QaToolPolicyPlan {
+    /** Exact names that must remain visible after the scoped restriction. */
+    readonly allow: readonly string[];
+    /** Configured names absent from the agent's composed tool view. */
+    readonly unknown: readonly string[];
+}
+/**
+ * Validate an allow-list against the complete agent-scoped view.
+ *
+ * Preset tools live on an ancestor scope, not necessarily in the global tool
+ * layer. The restriction must therefore retain the configured names verbatim;
+ * deriving it from the global view would hide every preset-owned tool after a
+ * successful first attestation and make the next attestation fail.
+ */
+export declare function qaToolPolicyPlan(allow: readonly string[], isMounted: (toolName: string) => boolean): QaToolPolicyPlan;
+/** Monotonic execution decision shared by inherited, scoped and transport tools. */
+export declare function qaToolDenial(allowed: ReadonlySet<string>, toolName: string): string | undefined;
+//# sourceMappingURL=lockdown-policy.d.ts.map

package/lib/types/secure-session.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * Host-side QA policy admission boundary — the only browser-callable operation
+ * that turns a session into a locked QA session. It verifies the immutable
+ * session composition against the effective deployment config, refuses to
+ * adopt a non-QA session with user history, validates the named permission
+ * preset, pins the scoped tool restriction plus the monotonic execution guard,
+ * and returns a sanitized proof. Every refusal carries only a coarse reason.
+ */
+export declare class QaPolicyAdmission {
+    private readonly ctx;
+    private readonly config;
+    private readonly logger;
+    private readonly appliedPolicies;
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger);
+    secureSession(sessionId: string): QaLockdownProof;
+    /** Detach every pinned tool policy; wired as a disposal effect by the entry. */
+    dispose(): void;
+}
+//# sourceMappingURL=secure-session.d.ts.map