@yadsh/dsh-qa-surface 0.3.0 → 0.5.0

package/lib/types/client/use-session-ui-state.d.ts

@@ -1,10 +1,12 @@
 import { type Dispatch, type SetStateAction } from "react";
-import type { QaImageDraft, QaSource, QaTurnSources } from "../types.js";
+import type { QaAttachmentDraft, QaSource, QaTurnSources } from "../types.js";
 /** Snapshot completeness captured when a drawer was opened from a message. */
 export interface QaDrawerCompleteness {
     readonly complete: boolean;
     readonly incompleteOrigins?: QaTurnSources["incompleteOrigins"];
 }
+/** The rail tab ids; the agents drawer has not become a tab yet. */
+export type QaRailTab = "sources" | "files";
 export interface QaSessionUiState {
     /** Per group: how many answers back from the newest is shown (0 = newest). */
     readonly variantOffsets: Record<string, number>;
@@ -14,22 +16,26 @@ export interface QaSessionUiState {
     readonly setActiveTurn: Dispatch<SetStateAction<number | null>>;
     readonly agentsOpen: boolean;
     readonly setAgentsOpen: Dispatch<SetStateAction<boolean>>;
-    readonly sourcesOpen: boolean;
-    readonly setSourcesOpen: Dispatch<SetStateAction<boolean>>;
+    /** Whether the right rail column is shown. */
+    readonly railOpen: boolean;
+    readonly setRailOpen: Dispatch<SetStateAction<boolean>>;
+    /** Which rail tab is active; meaningful only while the rail is open. */
+    readonly railTab: QaRailTab;
+    readonly setRailTab: Dispatch<SetStateAction<QaRailTab>>;
     readonly drawerSources: readonly QaSource[] | null;
     readonly setDrawerSources: Dispatch<SetStateAction<readonly QaSource[] | null>>;
     readonly drawerCompleteness: QaDrawerCompleteness | null;
     readonly setDrawerCompleteness: Dispatch<SetStateAction<QaDrawerCompleteness | null>>;
     readonly drawerDetail: QaSource | null;
     readonly setDrawerDetail: Dispatch<SetStateAction<QaSource | null>>;
-    readonly pendingImages: readonly QaImageDraft[];
-    readonly setPendingImages: (next: readonly QaImageDraft[]) => void;
+    readonly pendingAttachments: readonly QaAttachmentDraft[];
+    readonly setPendingAttachments: (next: readonly QaAttachmentDraft[]) => void;
 }
 /**
  * Per-chat UI state: composer attachments, variant offsets, the rail mark and
  * the drawers. Everything here describes the chat it was made in, so a
- * session change clears it instead of leaking a draft, an image or a drawer
- * from one conversation into the next.
+ * session change clears it instead of leaking a draft, an attachment or a
+ * drawer from one conversation into the next.
  */
 export declare function useSessionUiState(sessionId: string | null): QaSessionUiState;
 //# sourceMappingURL=use-session-ui-state.d.ts.map

package/lib/types/config-resolvers/accounts.d.ts

@@ -0,0 +1,15 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+type AccountsSlice = ResolvedQaSurfaceConfig["accounts"];
+/** Resolved neighbors the per-user workspace boundary is checked against. */
+export interface AccountsDependencies {
+    readonly session: ResolvedQaSurfaceConfig["session"];
+    readonly lockdown: ResolvedQaSurfaceConfig["lockdown"];
+}
+/**
+ * Resolve the accounts domain. The per-user workspace boundary spans session
+ * and lockdown, so their resolved slices arrive as dependencies and the
+ * boundary checks run here, next to the flag they guard.
+ */
+export declare function resolveAccounts(input: QaSurfaceConfig, dependencies: AccountsDependencies): AccountsSlice;
+export {};
+//# sourceMappingURL=accounts.d.ts.map

package/lib/types/config-resolvers/attachments.d.ts

@@ -0,0 +1,6 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+type AttachmentsSlice = ResolvedQaSurfaceConfig["attachments"];
+/** Resolve the attachments domain: intake toggles and byte/line bounds. */
+export declare function resolveAttachments(input: QaSurfaceConfig): AttachmentsSlice;
+export {};
+//# sourceMappingURL=attachments.d.ts.map

package/lib/types/config-resolvers/basics.d.ts

@@ -0,0 +1,8 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+export declare function normalizeRoutePath(value: string): string;
+/** The scalar domains that carry no table-shaped or cross-domain rules. */
+type BasicsSlice = Pick<ResolvedQaSurfaceConfig, "enabled" | "route" | "branding" | "embedding" | "entry" | "interaction">;
+/** Resolve the master switch, route, branding, embedding, and entry domains. */
+export declare function resolveBasics(input: QaSurfaceConfig): BasicsSlice;
+export {};
+//# sourceMappingURL=basics.d.ts.map

package/lib/types/config-resolvers/defaults.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+/** The canonical resolved config; every domain resolver defaults from it. */
+export declare const DEFAULT_QA_SURFACE_CONFIG: ResolvedQaSurfaceConfig;
+//# sourceMappingURL=defaults.d.ts.map

package/lib/types/config-resolvers/lockdown.d.ts

@@ -0,0 +1,10 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+type LockdownSlice = ResolvedQaSurfaceConfig["lockdown"];
+/**
+ * Resolve the lockdown domain. The capability flags are clamped shut, and
+ * showing the reset control needs an explicit authorization here, so the
+ * resolved UI slice arrives as a neighbor.
+ */
+export declare function resolveLockdown(input: QaSurfaceConfig, ui: ResolvedQaSurfaceConfig["ui"]): LockdownSlice;
+export {};
+//# sourceMappingURL=lockdown.d.ts.map

package/lib/types/config-resolvers/session.d.ts

@@ -0,0 +1,6 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+type SessionSlice = ResolvedQaSurfaceConfig["session"];
+/** Resolve the session domain: policy, pinning, and model selection. */
+export declare function resolveSession(input: QaSurfaceConfig): SessionSlice;
+export {};
+//# sourceMappingURL=session.d.ts.map

package/lib/types/config-resolvers/shared.d.ts

@@ -0,0 +1,23 @@
+/** Trim an optional string; a blank value collapses to null. */
+export declare function optionalText(value: string | null | undefined): string | null;
+/**
+ * Whether a configured directory is absolute. The rule reads a drive-letter
+ * path as absolute on every platform, like `session.cwd` does: a deployment
+ * profile is authored on one machine and may be read on another, so a
+ * Windows-style root is not a mistake to reject on a POSIX host.
+ */
+export declare function isAbsoluteDirectoryPath(value: string): boolean;
+/**
+ * Shared numeric guard for operator-tuned limits: the value has to be a safe
+ * integer inside [min, max], and every rejection carries the same message.
+ */
+export declare function assertIntInRange(name: string, value: number, min: number, max: number): void;
+/** Deduplicate and trim the operator's quick questions. */
+export declare function uniqueQuestions(values: readonly string[]): readonly string[];
+/**
+ * Normalize the operator's phrase list. Unlike quick questions, an empty list
+ * cannot mean "hide the control": the running indicator has to say something,
+ * so emptiness restores the built-in phrases.
+ */
+export declare function uniquePhrases(values: readonly string[]): readonly string[];
+//# sourceMappingURL=shared.d.ts.map

package/lib/types/config-resolvers/sources.d.ts

@@ -0,0 +1,6 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+type SourcesSlice = ResolvedQaSurfaceConfig["sources"];
+/** Resolve the sources domain: collection, display, and preview bounds. */
+export declare function resolveSources(input: QaSurfaceConfig): SourcesSlice;
+export {};
+//# sourceMappingURL=sources.d.ts.map

package/lib/types/config-resolvers/ui.d.ts

@@ -0,0 +1,6 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+type UiSlice = ResolvedQaSurfaceConfig["ui"];
+/** Resolve the UI domain: widget visibility and the content width floor. */
+export declare function resolveUi(input: QaSurfaceConfig): UiSlice;
+export {};
+//# sourceMappingURL=ui.d.ts.map

package/lib/types/index.d.ts

@@ -1,10 +1,11 @@
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import type { Context } from "@deepseek-ai/cordis";
 import type { QaTurnSources } from "./provenance/types.js";
-import type { QaAccountSession, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSourceFilePreview, QaWhoamiResult } from "./types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSourceFilePreview, QaWhoamiResult } from "./types.js";
 export declare const name = "qa-surface";
 export declare const inject: string[];
-export declare const QA_SURFACE_SETTINGS_NAMESPACE = "qa-surface";
+import { QA_SURFACE_SETTINGS_NAMESPACE } from "./shared/settings.js";
+export { QA_SURFACE_SETTINGS_NAMESPACE };
 export declare const Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
 declare module "@deepseek-ai/cordis" {
     interface Context {
@@ -18,24 +19,18 @@ export declare class QaSurface extends TypertRemoteService {
     private source;
     private readonly logger;
     private readonly admission;
+    private readonly approvals;
+    private readonly userQuestions;
     private readonly provenance;
-    private accounts;
-    private accountsOptions;
+    private readonly notes;
+    /** Account-remote bodies; the wire signatures stay on this class. */
+    private readonly accountRemotes;
     private readonly launchToken;
     private webServer;
     private disposeRoute;
     private routeKey;
     constructor(ctx: Context, entry?: QaSurfaceConfig);
     getConfig(): ResolvedQaSurfaceConfig;
-    /**
-     * The accounts store behind the runtime toggle. Rebuilt only when the
-     * account-affecting options change; the file is shared across rebuilds.
-     */
-    private accountsFor;
-    /** The accounts store, or the disabled refusal the browser maps to copy. */
-    private requireAccounts;
-    /** Account failures ride the shared `(reason: <code>)` wire marker. */
-    private accountsRemote;
     /**
      * Self-service signup; the first account ever created becomes admin. The
      * display name derives from the email: the generated client enforces exact
@@ -59,6 +54,13 @@ export declare class QaSurface extends TypertRemoteService {
     accountsListOwnership(token: string): {
         readonly entries: readonly QaOwnershipEntry[];
     };
+    /**
+     * Replace the caller's own self-declared profile. The token is the only
+     * identity the wire carries: a browser can never name a profile but its own,
+     * and the deployment's declared fields and length limits are enforced in the
+     * store before anything is written.
+     */
+    accountsUpdateProfile(token: string, input: QaAccountProfileInput): QaAccountUserPublic;
     /**
      * 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
@@ -67,10 +69,40 @@ export declare class QaSurface extends TypertRemoteService {
      * boundary stays in {@link secureSession}.
      */
     describe(): ResolvedQaSurfaceConfig;
+    /**
+     * Create a QA session from Host-owned inputs. With account workspaces on,
+     * cwd is `<configured workspace>/.qa-users/<account UUID>` and the child is
+     * intentionally not registered or attached as another DSH workspace.
+     */
+    createSession(token: string): Promise<string>;
     /** Pin and attest the effective policy. The browser supplies identity only. */
-    secureSession(token: string, sessionId: string): QaLockdownProof;
+    secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
     /** Return canonical Host snapshots; replay is rebuilt from qa/sources events. */
-    sources(token: string, sessionId: string): readonly QaTurnSources[];
+    sources(token: string, sessionId: string): Promise<readonly QaTurnSources[]>;
+    /**
+     * The tool calls of one chat that wait for the operator. Read-only: a
+     * deployment with blocked approvals answers with an empty list.
+     */
+    pendingApprovals(token: string, sessionId: string): Promise<readonly QaPendingApproval[]>;
+    /**
+     * Apply the operator's answer to one parked call. The id must belong to a
+     * request of this chat; an answer that lost the race (the turn was stopped,
+     * the agent went away) is refused with `false`.
+     */
+    answerApproval(token: string, sessionId: string, requestId: string, decision: QaApprovalDecision): Promise<boolean>;
+    /**
+     * The questions of one chat that wait for the operator. Read-only: a
+     * deployment with unsupported questions answers with an empty list.
+     */
+    pendingQuestions(token: string, sessionId: string): Promise<readonly QaPendingQuestion[]>;
+    /**
+     * Apply the operator's answers to one parked question request. Every question
+     * of the request must be present in `answers`; one the browser omits reads as
+     * a skip.
+     */
+    answerQuestion(token: string, sessionId: string, requestId: string, answers: readonly QaQuestionAnswerItem[]): Promise<boolean>;
+    /** Close a parked question request without answering it. */
+    cancelQuestion(token: string, sessionId: string, requestId: string): Promise<boolean>;
     /** Narrow read-only preview capability for files already present as sources. */
     readSourceFile(token: string, sessionId: string, sourcePath: string): Promise<QaSourceFilePreview>;
     private refreshRoute;
@@ -83,6 +115,7 @@ export { entryRedirectRow, entryRedirectScript } from "./entry-redirect.js";
 export { registerQaNavigationRoute } from "./host-route.js";
 export { qaToolDenial, qaToolPolicyPlan } from "./lockdown-policy.js";
 export { QaPolicyAdmission } from "./secure-session.js";
+export { QaPromptNotes, renderUserIdentity, QA_IDENTITY_NOTE, QA_SOURCES_NOTE, } from "./prompt-notes.js";
 export * from "./provenance/index.js";
 export type * from "./types.js";
 export default QaSurface;

package/lib/types/profile.d.ts

@@ -0,0 +1,76 @@
+import type { QaAccountIdentityField, QaAccountProfile } from "./types.js";
+/**
+ * Profile shape, limits, and the normalization both halves of the plugin
+ * agree on. Deliberately free of Node built-ins: the configuration resolver
+ * and the browser-side form import these same limits, and a Host-only import
+ * here would drag the accounts store into the client bundle.
+ */
+/** Longest accepted full name. */
+export declare const QA_PROFILE_MAX_FULL_NAME = 200;
+/** Longest accepted value of one external-system handle. */
+export declare const QA_PROFILE_MAX_IDENTITY_VALUE = 200;
+/** Most handles one profile may carry. */
+export declare const QA_PROFILE_MAX_IDENTITIES = 16;
+/** Handle keys are lowercase labels; the deployment declares which ones exist. */
+export declare const QA_PROFILE_IDENTITY_KEY: RegExp;
+/** Longest accepted display label of one declared handle field. */
+export declare const QA_PROFILE_MAX_IDENTITY_LABEL = 40;
+/** Most handle fields one deployment may declare. */
+export declare const QA_PROFILE_MAX_IDENTITY_FIELDS = 8;
+/** Default cap on the user's free-form agent guidance. */
+export declare const QA_PROFILE_DEFAULT_INSTRUCTIONS_MAX = 2000;
+/** Bounds within which a deployment may set that cap. */
+export declare const QA_PROFILE_INSTRUCTIONS_MAX_MIN = 200;
+export declare const QA_PROFILE_INSTRUCTIONS_MAX_MAX = 20000;
+/** The profile of an account that never filled one in. */
+export declare function emptyProfile(): QaAccountProfile;
+/**
+ * Read one stored (or wire-delivered) profile into its public shape. Unknown
+ * or hand-edited input degrades to the readable subset instead of throwing:
+ * a malformed profile must never cost the account its session. Overlong text
+ * is truncated here — the write path rejects it with a message instead.
+ */
+export declare function normalizeProfile(value: unknown): QaAccountProfile;
+/** Validated profile values, before the store stamps `updatedAt`. */
+export interface QaProfileWrite {
+    readonly fullName: string;
+    readonly identities: Readonly<Record<string, string>>;
+    readonly instructions: string;
+}
+export type QaProfileWriteResult = {
+    readonly ok: true;
+    readonly value: QaProfileWrite;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export interface QaProfileWriteOptions {
+    readonly instructionsMaxLength: number;
+    /**
+     * Fields the deployment declares; a write may name only these keys. Omit to
+     * check the key shape alone — the operator CLI path, where the writer is the
+     * same person who owns the configuration.
+     */
+    readonly identities?: readonly QaAccountIdentityField[];
+}
+/**
+ * Validate one full-replace profile write. Values are cleaned the same way
+ * the read path cleans them, so what a caller sends is what the prompt will
+ * later render; limits are refused with a message instead of truncated, so a
+ * user pasting an essay learns why it was not stored.
+ */
+export declare function validateProfileWrite(input: unknown, options: QaProfileWriteOptions): QaProfileWriteResult;
+export type QaIdentityFieldsResult = {
+    readonly ok: true;
+    readonly value: readonly QaAccountIdentityField[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Validate the deployment's declared handle fields: the profile form renders
+ * one input per entry and the prompt names exactly these, so a typo in a key
+ * becomes a refusal at configuration time rather than a silent no-op.
+ */
+export declare function validateIdentityFields(value: unknown): QaIdentityFieldsResult;
+//# sourceMappingURL=profile.d.ts.map

package/lib/types/prompt-notes.d.ts

@@ -0,0 +1,110 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaAccounts } from "./accounts/store.js";
+import type { QaAccountIdentityField, QaAccountProfile, ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * Plugin marker on every injected message. The chat projection turns a
+ * plugin-sourced user message into injected context rather than a chat
+ * bubble, and the QA transcript keeps exactly those hidden.
+ */
+export declare const QA_NOTES_PLUGIN = "qa-surface";
+/** Note name carrying who the assistant is talking to. */
+export declare const QA_IDENTITY_NOTE = "dsh-qa-surface:user-identity";
+/** Note name carrying the deployment's rule about source provenance. */
+export declare const QA_SOURCES_NOTE = "dsh-qa-surface:structured-sources";
+export interface QaIdentityRenderInput {
+    /** The owner's account address; the one fact accounts always provide. */
+    readonly email: string;
+    readonly profile: QaAccountProfile;
+    /** Handle fields the deployment declares, in its configured order. */
+    readonly identities: readonly QaAccountIdentityField[];
+}
+/** The two identity parts one user resolves to; either may be empty. */
+export interface QaRenderedIdentity {
+    readonly identity: string;
+    readonly instructions: string;
+}
+/**
+ * Render the identity text for one attested user.
+ *
+ * The wording is deliberately explicit about provenance: these are the user's
+ * own claims, so the model is told to name the identifier it searched by and
+ * to ask when the results contradict the request. A wrong handle that the
+ * model trusts silently is the failure mode this text exists to prevent.
+ */
+export declare function renderUserIdentity(input: QaIdentityRenderInput): QaRenderedIdentity;
+/** One named block the injector can add to a step. */
+export interface QaPromptNote {
+    /** Source-section name, and the marker that finds the note again. */
+    readonly name: string;
+    readonly text: string;
+}
+export interface QaPromptNotesOptions {
+    readonly config: () => ResolvedQaSurfaceConfig;
+    /** The live accounts store, or undefined while accounts are disabled. */
+    readonly accounts: () => QaAccounts | undefined;
+    /**
+     * Whether one session belongs to the QA surface. The admission answers it:
+     * only an attested session reaches the QA audience the notes are written
+     * for, and delegated children resolve through their root session.
+     */
+    readonly isQaSession: (sessionId: string) => boolean;
+    readonly logger: PluginLogger;
+}
+/**
+ * Delivers the QA surface's ambient notes to the agent: who the assistant is
+ * talking to, and what the deployment expects around source provenance.
+ *
+ * A system-prompt section would be the natural home for both, and this plugin
+ * used one for each. Neither survives the QA deployment's own preset: the
+ * `qa-research` persona registers with `complete: true` (the persona IS the
+ * whole system prompt, so every other section is discarded) and
+ * `includeRuntimeContext: false` (which drops every context contribution as
+ * well). The preset says so outright — no plugin adds prompt text.
+ *
+ * What stays open is the conversation: a plugin-sourced user message is
+ * admitted to the request as injected context, survives both switches, and
+ * the transcript projection already hides every non-`subagent` context note
+ * from the QA audience. Each note is written once per text rather than once
+ * per step — the session's own surface is the state, so a resume or a plugin
+ * reload never duplicates a note — and written again only when its text
+ * actually changes.
+ *
+ * The notes are advisory text, never authority: nothing here is enforced by
+ * the model's compliance. The lockdown (allow-list, guards, permission
+ * preset) is host-side and holds whatever the conversation says.
+ */
+export declare class QaPromptNotes {
+    private readonly ctx;
+    private readonly options;
+    /** `${agentId}:${noteName}` → the text the note already carries. */
+    private readonly carried;
+    private readonly disposePreStep;
+    private disposed;
+    constructor(ctx: Context, options: QaPromptNotesOptions);
+    dispose(): void;
+    /** Append every note whose text this step does not already carry. */
+    private inject;
+    /** Who is asking: the owner's name, handles and their own instructions. */
+    private identityNotes;
+    /** What the deployment expects around the sources the surface collects. */
+    private sourcesNotes;
+    private carriedKey;
+    /**
+     * The text one note already carries in this agent's conversation. Process
+     * memory answers it after the first step; a cold read walks the durable
+     * surface so a resumed session or a reloaded plugin does not write twice.
+     */
+    private carriedText;
+    /**
+     * The session a chat started from. Delegated children are joined to their
+     * preset's standing scope rather than to their parent agent, so the chain
+     * has to be walked through the durable session headers; an unresolvable link
+     * (a resumed session whose parent is no longer loaded) degrades to the
+     * farthest ancestor known at that moment.
+     */
+    private rootSessionId;
+    /** The owner's email and profile, or nothing while the chat is anonymous. */
+    private identityOf;
+}
+//# sourceMappingURL=prompt-notes.d.ts.map

package/lib/types/provenance/reported.d.ts

@@ -1,5 +1,13 @@
 import { canonicalizeUrl } from "./normalize.js";
 import type { QaReportedSource, QaSourceOrigin, QaSourceReference } from "./types.js";
+export interface ReportedSourceOptions {
+    /**
+     * Whether a reported source must carry an address to be recorded. With
+     * `false`, a source the model wrote without a usable path or URL keeps its
+     * own type, title and snippet instead of being dropped.
+     */
+    readonly validate?: boolean;
+}
 /** Normalize a source explicitly reported by a delegated provider. */
-export declare function normalizeReportedSource(source: QaReportedSource, origin: QaSourceOrigin, workspaceRoot?: string, urlOptions?: Parameters<typeof canonicalizeUrl>[1]): QaSourceReference | null;
+export declare function normalizeReportedSource(source: QaReportedSource, origin: QaSourceOrigin, workspaceRoot?: string, urlOptions?: Parameters<typeof canonicalizeUrl>[1], options?: ReportedSourceOptions): QaSourceReference | null;
 //# sourceMappingURL=reported.d.ts.map

package/lib/types/questions.d.ts

@@ -0,0 +1,83 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaSessionOwnership } from "./session-ownership.js";
+import type { QaPendingQuestion, QaQuestionAnswerItem } from "./types.js";
+/**
+ * The harness user-questions contract this seam reads and writes, declared
+ * structurally on purpose: the plugin neither mounts the service nor depends on
+ * its package, so it stays loadable in a deployment that composes no questions
+ * at all. Shapes follow `@deepseek-ai/dsh-user-questions` `src/types.ts` at the
+ * tested harness release (`AskUserQuestionItem` / `AskUserQuestionAnswer`).
+ */
+export interface QaQuestionOption {
+    readonly label: string;
+    readonly description?: string;
+}
+export interface QaQuestionItem {
+    readonly id: string;
+    readonly question: string;
+    readonly detail?: string;
+    readonly header?: string;
+    readonly options?: readonly QaQuestionOption[];
+    readonly multiSelect?: boolean;
+}
+export interface QaQuestionRequest {
+    readonly questions: readonly QaQuestionItem[];
+    readonly agent?: Agent;
+    readonly signal?: AbortSignal;
+}
+/** What the answerer waterfall accepts as its value. */
+export interface QaQuestionAnswer {
+    readonly answers: readonly QaQuestionAnswerItem[];
+}
+/** What the model reads when the deployment does not answer questions. */
+export declare const QA_QUESTIONS_UNSUPPORTED = "questions are not answered in this assistant view; ask the user in plain text instead";
+/**
+ * User questions in the QA view.
+ *
+ * `ask_user_question` reaches the browser through the harness answerer
+ * waterfall, and the stock DSH web bundle mounts its own answerer in every
+ * page. Behind the QA overlay that answerer is unreachable, so a question asked
+ * of a QA chat would sit in front of nobody. This gate claims the request for
+ * attested chats before the generic browser bridge sees it:
+ *
+ * - `interaction.questions: interactive` parks the request until the operator
+ *   answers or closes it in the QA view, and the answer becomes the waterfall's
+ *   value.
+ * - `unsupported` (default) refuses with a reason the model can act on, rather
+ *   than letting the turn stall on a card no one can see.
+ *
+ * Nothing is ever answered on the operator's behalf, and a request from a
+ * session this deployment did not attest is handed back to the chain untouched.
+ */
+export declare class QaQuestionGate {
+    private readonly ctx;
+    private readonly interactive;
+    private readonly ownership;
+    private readonly logger;
+    private readonly pending;
+    private readonly disposers;
+    constructor(ctx: Context, interactive: () => boolean, ownership: QaSessionOwnership, logger: PluginLogger);
+    /** Claim question requests for the chats this deployment answers. */
+    install(): void;
+    /** Questions of one chat, oldest first: what the QA view renders. */
+    list(sessionId: string): readonly QaPendingQuestion[];
+    /**
+     * Apply the operator's answers; an unknown or foreign id is refused. The
+     * parked request is authoritative: a label the question never offered is
+     * dropped, and a free-text answer replaces the choice in a single-select
+     * rather than accompanying it, so the model only ever reads a real answer.
+     */
+    answer(sessionId: string, requestId: string, answers: readonly QaQuestionAnswerItem[]): boolean;
+    /** Close a request without answering it. */
+    cancel(sessionId: string, requestId: string): boolean;
+    /** Detach the listener and fail every parked request. Wired as an effect. */
+    dispose(): void;
+    private handle;
+    /** Park one request until the operator answers it, or the turn ends. */
+    private park;
+    /** Fail the questions one session's agent owns; a disposed agent cannot ask. */
+    private settleOwner;
+}
+//# sourceMappingURL=questions.d.ts.map

package/lib/types/resolve-config.d.ts

@@ -1,6 +1,11 @@
+import { normalizeRoutePath } from "./config-resolvers/basics.js";
+import { DEFAULT_QA_SURFACE_CONFIG } from "./config-resolvers/defaults.js";
 import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
-export declare const DEFAULT_QA_SURFACE_CONFIG: ResolvedQaSurfaceConfig;
-export declare function normalizeRoutePath(value: string): string;
-/** Materialize defaults and enforce route/session/model safety constraints. */
+export { DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath };
+/**
+ * Materialize defaults and enforce route/session/model safety constraints by
+ * running one resolver per config domain — in the order the checks have
+ * always fired — and assembling the frozen result.
+ */
 export declare function resolveConfig(input?: QaSurfaceConfig): ResolvedQaSurfaceConfig;
 //# sourceMappingURL=resolve-config.d.ts.map

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

@@ -7,7 +7,10 @@ import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
  * pair or throw the coarse `QaAttestationError`; see {@link QaAccounts}.
  */
 export interface QaAccountsGate {
-    enforceSessionAccess(token: string, sessionId: string): void;
+    enforceSessionAccess(token: string, sessionId: string): {
+        readonly id: string;
+    } | undefined;
+    userWorkspace(userId: string, registeredWorkspacePath: string): string;
 }
 /**
  * Host-side QA policy admission boundary — the only browser-callable operation
@@ -23,8 +26,49 @@ export declare class QaPolicyAdmission {
     private readonly logger;
     private readonly accounts?;
     private readonly appliedPolicies;
+    /**
+     * Sessions the QA surface has attested. The provenance note is written for
+     * exactly these, and a delegated child resolves through its root session, so
+     * one set answers for the whole chat.
+     */
+    private readonly attested;
+    private readonly workspaceAccess;
+    private readonly disposeWorkspaceGuard;
     constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined);
-    secureSession(token: string, sessionId: string): QaLockdownProof;
+    /**
+     * The mounted attachment store's verbatim root, when the backend exposes
+     * one. It sits outside every workspace, so the per-user fence would
+     * otherwise deny the model the exact file an upload produced and the prompt
+     * points it at. A backend without a resolvable root simply keeps the fence
+     * closed — attachments then only work where reads are not fenced per user.
+     */
+    private attachmentRoot;
+    /**
+     * The live agent for one session, resuming a Session the Host has not
+     * materialized in this process.
+     *
+     * DSH builds an agent on demand: a session's journal opens straight from
+     * persistence (`session/page` reads the durable log), and only Agent-bound
+     * operations — a prompt, a model selection, renaming, an upload — resolve or
+     * resume one. So a chat from an earlier Host run has a readable transcript
+     * and no agent at all, and attestation, which pins the tool policy ON that
+     * agent, is the first thing here that needs one. Refusing instead would make
+     * every restored chat unopenable until something else in the Host happened
+     * to wake it.
+     *
+     * The resume composes the session's OWN recorded preset — the same
+     * composition a stock prompt would produce — so a session composed outside
+     * the QA preset still lands on the mismatch refusals below ("composition
+     * mismatch"), and the adoption and permission checks stay the gate.
+     */
+    private liveAgent;
+    secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
+    /**
+     * Whether one session went through this boundary. The provenance note is
+     * written only for attested sessions, which is what keeps a deployment's
+     * source rules out of unrelated chats served by the same process.
+     */
+    knowsSession(sessionId: string): boolean;
     /** Detach every pinned tool policy; wired as a disposal effect by the entry. */
     dispose(): void;
 }

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

@@ -0,0 +1,30 @@
+import type { Context } from "@deepseek-ai/cordis";
+/**
+ * Which sessions belong to this deployment.
+ *
+ * The admission boundary attests chat roots. A delegated child never appears
+ * there — its scope chain does not reach the chat's own agent context — so it
+ * inherits its chat from the session that created it. Both interactive seams
+ * (tool approvals and user questions) read ownership from here, which is what
+ * keeps one chat answered by exactly one surface.
+ */
+export declare class QaSessionOwnership {
+    private readonly isAttested;
+    /** Child session → the attested chat that owns it. */
+    private readonly inherited;
+    private disposeListener;
+    private installed;
+    constructor(isAttested: (sessionId: string) => boolean);
+    /** Listen for the children of an attested chat; safe to call from each seam. */
+    install(ctx: Context): void;
+    /** The attested chat behind a session: itself, or the root it inherited. */
+    rootOf(sessionId: string): string | undefined;
+    /**
+     * Drop one session's inheritance. Called when its agent is gone; the chat's
+     * own claim needs no bookkeeping here, because it resolves through the
+     * admission's attested set, which owns that lifetime.
+     */
+    forget(sessionId: string): void;
+    dispose(): void;
+}
+//# sourceMappingURL=session-ownership.d.ts.map