@yadsh/dsh-qa-surface 0.3.0 → 0.5.0

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

@@ -0,0 +1,23 @@
+/**
+ * The QA Surface settings card.
+ *
+ * Two sources meet here: the `qa-surface` settings namespace, which is the
+ * page's configuration source on the Host, and the `qaSurface/describe`
+ * Remote, which reports the configuration the running Host actually resolved.
+ * Everything the user changes is written immediately as a path-addressed
+ * mutation; the status view re-reads the Remote while the card is visible, so
+ * a saved change is confirmed against the Host rather than against the form.
+ */
+import type { SettingsScope } from "@deepseek-ai/dsh-client-ui-settings/client";
+import type { InjectFace, PropsRuntime } from "@deepseek-ai/dsh-client-ui-slots";
+import type { RemoteResult } from "@deepseek-ai/dsh-typert-protocol";
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../../types.js";
+/** The face the slot entry injects into this card. */
+export interface QaSettingsCardFace {
+    readonly scope: SettingsScope<QaSurfaceConfig>;
+    describe(): Promise<RemoteResult<ResolvedQaSurfaceConfig>>;
+}
+type CardProps = PropsRuntime<"settings.plugin.item"> & InjectFace<QaSettingsCardFace>;
+export declare function QaSettingsCard({ scope, describe }: CardProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=card.d.ts.map

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

@@ -0,0 +1,139 @@
+/**
+ * Shared controls of the QA Surface card body.
+ *
+ * Every control edits the settings namespace through the same path-addressed
+ * write, and text and number drafts commit on blur or Enter rather than per
+ * keystroke: a half-typed path or an emptied number is a value the Host
+ * refuses, and a refusal mid-typing would clear the field the user is still
+ * editing. Controls that must land together (a provider with its model, the
+ * per-user sandbox with its flag) write every path in one mutation, because
+ * the Host validates the section as a whole.
+ */
+import { type ReactNode } from "react";
+import { type IdentityFieldDraft } from "./format.js";
+/** One field write inside the plugin's settings namespace. */
+export interface ConfigEntry {
+    readonly path: readonly string[];
+    readonly value: unknown;
+}
+/** Path-addressed write into the plugin's settings namespace. */
+export type ConfigWrite = (path: readonly string[], value: unknown) => void;
+/** Several path-addressed writes applied as one mutation. */
+export type ConfigWriteMany = (entries: readonly ConfigEntry[]) => void;
+/** Path-addressed clear, so the field re-inherits the composition layer. */
+export type ConfigUnset = (path: readonly string[]) => void;
+/** Whether the raw user layer carries a path. */
+export type OverrideCheck = (path: readonly string[]) => boolean;
+export interface SectionProps {
+    readonly writable: boolean;
+    readonly write: ConfigWrite;
+    readonly writeMany: ConfigWriteMany;
+    readonly unset: ConfigUnset;
+    readonly overridden: OverrideCheck;
+}
+/** Section frame: title, optional modified marker, optional trailing control. */
+export declare function Section(props: {
+    title: string;
+    modified: boolean;
+    hint?: ReactNode;
+    aside?: ReactNode;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Small clearing control shown beside a section the user layer overrides. */
+export declare function ResetButton(props: {
+    disabled: boolean;
+    label: string;
+    onClick: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** Two-state control with a label and an explanatory hint. */
+export declare function Toggle(props: {
+    checked: boolean;
+    disabled: boolean;
+    label: string;
+    hint: string;
+    onChange: (checked: boolean) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** Fixed-option control for the schema's string unions. */
+export declare function SelectField(props: {
+    label: string;
+    value: string;
+    disabled: boolean;
+    options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    hint?: string;
+    onChange: (value: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** Text control; the draft commits on blur and on Enter. */
+export declare function TextField(props: {
+    label: string;
+    value: string;
+    disabled: boolean;
+    placeholder?: string;
+    hint?: string;
+    multiline?: boolean;
+    rows?: number;
+    onChange: (value: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Whole-number control; the draft commits on blur and on Enter. A value
+ * outside the range snaps into it on commit, so the field never holds a
+ * number the Host would refuse outright.
+ */
+export declare function NumberField(props: {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    disabled: boolean;
+    hint?: string;
+    onChange: (value: number) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * List control for string arrays. The draft parses on commit so a separator
+ * the user is still typing never becomes a stored entry.
+ */
+export declare function ListField(props: {
+    label: string;
+    hint?: string;
+    value: readonly string[];
+    disabled: boolean;
+    placeholder?: string;
+    rows?: number;
+    parse: (text: string) => string[];
+    onCommit: (values: string[]) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * The deployment's declared profile fields, one `key = подпись` per line. The
+ * control keeps its own draft so a line still being typed is not parsed into
+ * the stored array.
+ */
+export declare function IdentitiesField(props: {
+    value: ReadonlyArray<{
+        readonly key?: string | undefined;
+        readonly label?: string | undefined;
+    }>;
+    disabled: boolean;
+    onCommit: (fields: IdentityFieldDraft[]) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** Status chip pair: label and value with the mode's tone. */
+export declare function Chip(props: {
+    label: string;
+    value: string;
+    tone?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/** Prose notice: informational or warning, never a control. */
+export declare function Notice(props: {
+    tone: "info" | "warn";
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Fixed facts of the composed policy, shown as label/value rows. */
+export declare function Facts(props: {
+    items: ReadonlyArray<{
+        label: string;
+        value: string;
+        note?: string;
+    }>;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=fields.d.ts.map

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

@@ -0,0 +1,108 @@
+/**
+ * Pure presentation helpers of the QA Surface settings card.
+ *
+ * Kept out of the components so the wording and the draft parsing are
+ * unit-testable without a DOM, and so every place that renders the same value
+ * renders it identically. Nothing here may reach the Host config surface: the
+ * card bundle must not pull schemastery into the page.
+ */
+import type { QaSurfaceConfig } from "../../types.js";
+/** A control's label with the sentence explaining what it does. */
+export interface DescribedOption {
+    readonly label: string;
+    readonly hint: string;
+}
+/**
+ * Header badge: the route the page answers on, or that the surface is off.
+ * The route is the one fact an operator scanning the plugin list looks for.
+ */
+export declare function badgeText(enabled: boolean | undefined, routePath: string | undefined): string;
+/** Wording of the session-policy control. */
+export declare function describeSessionPolicy(policy: string | undefined): DescribedOption;
+/** Wording of the sandbox-mode control. */
+export declare function describeSandbox(mode: string | undefined): DescribedOption;
+/**
+ * Parse a numeric control's draft text.
+ * @param text - raw input value.
+ * @param min - lowest accepted value, clamped into range on commit.
+ * @param max - highest accepted value, clamped into range on commit.
+ * @returns the integer, or null when the field is empty or not numeric (the
+ * caller leaves the stored value alone rather than writing a NaN).
+ */
+export declare function parseNumberDraft(text: string, min: number, max: number): number | null;
+/**
+ * Parse a one-entry-per-line list control's draft text. Questions and phrases
+ * are free copy, so a comma inside an entry must stay part of that entry.
+ */
+export declare function parseLineList(text: string): string[];
+/** Parse a list control whose entries may also be comma-separated. */
+export declare function parseCommaList(text: string): string[];
+/** One declared identity field as the operator writes it. */
+export interface IdentityFieldDraft {
+    readonly key: string;
+    readonly label: string;
+}
+/**
+ * Parse the identity-field control: one `key = подпись` entry per line. A
+ * missing label falls back to the key, and an entry whose key cannot exist on
+ * the Host is dropped here rather than refused as a whole write.
+ */
+export declare function parseIdentityFields(text: string): IdentityFieldDraft[];
+/** Render declared identity fields back into the control's draft text. */
+export declare function formatIdentityFields(fields: readonly IdentityFieldDraft[] | undefined): string;
+/**
+ * Prerequisites `accounts.perUserWorkspace` cannot run without. The Host
+ * refuses the configuration while any of them is unmet, and the sandbox mode
+ * is the one entry the card must write together with the flag: both
+ * `workspace-write` alone and per-user workspaces alone are refused.
+ */
+export declare function perUserWorkspaceGaps(config: QaSurfaceConfig): string[];
+/**
+ * Whether the raw user layer carries this path, which is what marks a field
+ * overridden — a value equal to the composition default is still an override.
+ * @param user - raw user section from the settings snapshot.
+ * @param path - path from the section root.
+ * @returns true when every segment exists in the user layer.
+ */
+export declare function isOverridden(user: unknown, path: readonly string[]): boolean;
+/** Top-level keys the user layer carries; the reset-all action clears exactly these. */
+export declare function overriddenKeys(user: unknown): string[];
+/**
+ * Read a path out of a settings section.
+ * @param value - section root (the snapshot's effective value or user layer).
+ * @param path - path from the section root.
+ * @returns the value found, or undefined when any segment is absent.
+ */
+export declare function readPath(value: unknown, path: readonly string[]): unknown;
+/**
+ * Whether a settled mutation left the section holding what it asked for.
+ *
+ * The scope resolves a Host-rejected write instead of rejecting it — it
+ * reloads Host state and returns — so acceptance is confirmed here. The
+ * namespace revision advances on every committed change, and a write that
+ * changed nothing is indistinguishable from a refusal; in that one case the
+ * section itself answers whether the value already stood.
+ * @param entries - writes the mutation asked for.
+ * @param cleared - paths the mutation asked to clear.
+ * @param snapshot - the scope snapshot as it stands after the settlement.
+ * @returns true when the mutation's intent is visible in the section.
+ */
+export declare function mutationLanded(entries: readonly {
+    readonly path: readonly string[];
+    readonly value: unknown;
+}[], cleared: readonly (readonly string[])[], snapshot: {
+    readonly value: unknown;
+    readonly user: unknown;
+}): boolean;
+/** Wall-clock stamp of the last Host answer, for the status line. */
+export declare function formatClock(timestamp: number | undefined): string;
+/**
+ * Count with the Russian form of its noun: 1 ключ, 2 ключа, 5 ключей.
+ * @param count - counted value.
+ * @param forms - singular, few, and many forms of the noun.
+ * @returns the counted noun as the copy renders it.
+ */
+export declare function pluralRu(count: number, forms: readonly [string, string, string]): string;
+/** Thousands separator so long byte budgets stay readable. */
+export declare function formatCount(value: number | undefined): string;
+//# sourceMappingURL=format.d.ts.map

package/lib/types/client/settings/sections/access.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Access and route: the only section whose consequences reach beyond this
+ * plugin's namespace — the path it claims on the Host and where external
+ * visitors of the harness root land.
+ */
+import { type ConfigProps } from "./common.js";
+/** Where the page lives and who may reach it. */
+export declare function AccessSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=access.d.ts.map

package/lib/types/client/settings/sections/accounts.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Accounts: the account gate, the self-declared profile, and per-user
+ * workspaces. The per-user toggle lands together with the sandbox mode —
+ * the Host accepts that pairing or nothing.
+ */
+import { type ConfigProps } from "./common.js";
+/** The account gate, the self-declared profile, and per-user workspaces. */
+export declare function AccountsSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=accounts.d.ts.map

package/lib/types/client/settings/sections/attachments.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Attachments: what a visitor may attach to one message. Like the interface
+ * section, the list fields show the value in effect — a stored list, else the
+ * Host's resolved one — so an untouched deployment never sees an empty box
+ * for a setting that is active.
+ */
+import { type ConfigProps } from "./common.js";
+/**
+ * What a visitor may attach to one message. Files never ride the prompt
+ * inline: the browser stages them on the Host and the prompt cites the
+ * receipt, so the model resolves the stored copy through its file tools — the
+ * deployment's tool allow-list has to keep `read` for that to be useful.
+ */
+export declare function AttachmentsSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=attachments.d.ts.map

package/lib/types/client/settings/sections/branding.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Branding: pure copy the visitor reads, so nothing here constrains what the
+ * Host accepts — every field is free-form and safe to leave empty.
+ */
+import { type ConfigProps } from "./common.js";
+/** Titles, welcome copy, and the notice under the composer. */
+export declare function BrandingSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=branding.d.ts.map

package/lib/types/client/settings/sections/common.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the config sections share: the props every section receives, the
+ * override check behind the modified marker, and the reset control that
+ * clears a whole section with one click.
+ */
+import type { ReactNode } from "react";
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../../../types.js";
+import { type SectionProps } from "../fields.js";
+export interface ConfigProps extends SectionProps {
+    readonly config: QaSurfaceConfig | undefined;
+    /**
+     * What the running Host resolved, when it answered. A control whose default
+     * is not a literal — the running phrases — reads the effective list from
+     * here instead of showing an empty field for a setting that is in effect.
+     */
+    readonly effective: ResolvedQaSurfaceConfig | null;
+}
+/** The setting paths one section owns; its reset clears them in order. */
+export type SectionPaths = ReadonlyArray<readonly string[]>;
+/** Whether the user layer overrides any of the paths the section owns. */
+export declare function overriddenAny(props: ConfigProps, paths: SectionPaths): boolean;
+/**
+ * The reset control beside a section whose paths the user layer overrides:
+ * one button clearing every path of the section, disabled while the settings
+ * namespace itself is read-only.
+ */
+export declare function resetAside(props: ConfigProps, paths: SectionPaths): ReactNode;
+//# sourceMappingURL=common.d.ts.map

package/lib/types/client/settings/sections/embedding.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Embedding: one CSP field with a wide blast radius — an overly generous
+ * frame-ancestors list lets any listed site run this page as its own UI.
+ */
+import { type ConfigProps } from "./common.js";
+/** Embedding the page into another site's frame. */
+export declare function EmbeddingSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=embedding.d.ts.map

package/lib/types/client/settings/sections/interface.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Interface: what the visitor sees of the conversation. The show-reset toggle
+ * stays disabled while the lockdown section withholds session reset — the
+ * Host refuses one without the other.
+ */
+import { type ConfigProps } from "./common.js";
+/** What the visitor sees of the conversation. */
+export declare function InterfaceSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=interface.d.ts.map

package/lib/types/client/settings/sections/lockdown.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lockdown: the execution policy every QA chat is pinned to. Its fixed
+ * choices are not editable on purpose — the Host rejects any configuration
+ * that relaxes them, so the card explains rather than offers.
+ */
+import { type ConfigProps } from "./common.js";
+/** The execution policy every QA chat is pinned to. */
+export declare function LockdownSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=lockdown.d.ts.map

package/lib/types/client/settings/sections/session.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Session: which chat a visitor gets, and which agent and model serve it.
+ * Provider and model are written as one mutation because the Host refuses
+ * either of them alone.
+ */
+import { type ConfigProps } from "./common.js";
+/** Which chat a visitor gets, and which agent and model serve it. */
+export declare function SessionSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=session.d.ts.map

package/lib/types/client/settings/sections/sources.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Sources: which sources the assistant may cite and how they are shown. Most
+ * of the controls live behind "advanced" disclosures so the default view
+ * carries only the collection switches a deployment actually argues about.
+ */
+import { type ConfigProps } from "./common.js";
+/** Which sources the assistant may cite, and how they are shown. */
+export declare function SourcesSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=sources.d.ts.map

package/lib/types/client/settings/sections/status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The status view: what the deployment actually serves, read from the running
+ * Host rather than from the settings snapshot.
+ */
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../../../types.js";
+export interface StatusProps {
+    /** Effective configuration the running Host answered with, when it did. */
+    readonly effective: ResolvedQaSurfaceConfig | null;
+    /** Settings snapshot shown while the Host has not answered. */
+    readonly config: QaSurfaceConfig | undefined;
+    readonly refreshing: boolean;
+    readonly refreshedAt: number | undefined;
+    readonly overrides: number;
+    readonly onRefresh: () => void;
+}
+/**
+ * What the deployment is actually serving: the route, the session policy, the
+ * execution policy, and the account gate, as the Host resolved them. The card
+ * polls this while it is open, so a saved change is confirmed here.
+ */
+export declare function StatusSection(props: StatusProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=status.d.ts.map

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

@@ -0,0 +1,25 @@
+/**
+ * Body sections of the QA Surface settings card.
+ *
+ * Each section owns its controls and derives every value from the settings
+ * snapshot (the effective configuration) or, for the status view, from the
+ * running Host through the `qaSurface/describe` Remote. The controls mirror
+ * the Host's own validation: combinations the resolver refuses are either
+ * written together in one mutation or explained rather than offered.
+ *
+ * One file per section lives in `sections/`, with what the config sections
+ * share in `sections/common.tsx`; this module is the barrel the card imports.
+ */
+export type { ConfigProps } from "./sections/common.js";
+export { AccessSection } from "./sections/access.js";
+export { AccountsSection } from "./sections/accounts.js";
+export { AttachmentsSection } from "./sections/attachments.js";
+export { BrandingSection } from "./sections/branding.js";
+export { EmbeddingSection } from "./sections/embedding.js";
+export { InterfaceSection } from "./sections/interface.js";
+export { LockdownSection } from "./sections/lockdown.js";
+export { SessionSection } from "./sections/session.js";
+export { SourcesSection } from "./sections/sources.js";
+export { StatusSection } from "./sections/status.js";
+export type { StatusProps } from "./sections/status.js";
+//# sourceMappingURL=sections.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * Card stylesheet: the canonical shell (AGENTS.md contract) plus body rules
+ * for this plugin's own controls. Every surface, border, and colour comes from
+ * `--dsw-alias-*` tokens so light, dark, and system themes stay coherent; the
+ * QA page's own palette stays out of the settings page.
+ */
+export declare const QA_SETTINGS_STYLES: string;
+//# sourceMappingURL=styles.d.ts.map

package/lib/types/client/stream-publisher.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Spacing for a running turn's stream frames. A running turn's frames arrive
+ * at animation-frame cadence, so re-projections are spaced at least the
+ * configured interval 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, and a
+ * non-running notification also cancels an absorbed window so the final
+ * state never waits for it. Zero disables the spacing entirely.
+ */
+export declare class StreamPublisher {
+    private readonly intervalMs;
+    private timer;
+    constructor(intervalMs: number);
+    /**
+     * Deliver one notification. `running` says whether the bound session is
+     * mid-turn; `emit` performs the actual projection and must stay cheap to
+     * defer.
+     */
+    publish(running: boolean, emit: () => void): void;
+    /**
+     * Cancel an absorbed window so the next frame projects at once. Called
+     * when the binding goes away or the controller winds down: a stale window
+     * must not swallow the first frame of a fresh binding.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=stream-publisher.d.ts.map

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

@@ -1,7 +1,7 @@
 import type { ClientRemote } from "@deepseek-ai/dsh-api-gateway/client";
 import type { ISessions, SessionFace } from "@deepseek-ai/dsh-api-session-controller/client";
 import type { UiConversation } from "@deepseek-ai/dsh-client-ui-conversation/client";
-import type { QaAccountSession, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaSessionState, QaSourceFilePreview, QaTurnSources, QaWhoamiResult } from "../types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSessionState, QaSourceFilePreview, QaTurnSources, QaWhoamiResult } from "../types.js";
 /** 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. */
@@ -28,6 +28,32 @@ export type QaSecureSession = (token: string, sessionId: string) => Promise<{
     readonly ok: false;
     readonly error: unknown;
 }>;
+/** Host-authoritative creation: identity, cwd and policy never come from the browser. */
+export type QaCreateSession = (token: string) => Promise<RemoteResult<string>>;
+/**
+ * Browser file-upload service (`ctx.fileUpload`), described structurally on
+ * purpose: files do not ride the prompt inline the way images do, they are
+ * staged through the Host upload route and cited by receipt. The QA bundle
+ * must not link the upload package — a deployment may not serve it — so the
+ * service is read off the context at send time and this is the only shape the
+ * surface relies on.
+ */
+export interface QaFileUpload {
+    upload(sessionId: string, data: Blob | Uint8Array, name?: string, signal?: AbortSignal): Promise<{
+        readonly ok: true;
+        readonly value: {
+            readonly receiptId: string;
+            readonly file: {
+                readonly attachmentId: string;
+                readonly name: string;
+                readonly bytes: number;
+            };
+        };
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+}
 export interface QaSourceApi {
     sources(token: string, sessionId: string): Promise<{
         readonly ok: true;
@@ -61,6 +87,53 @@ export type QaBoundSourceApi = {
         readonly error: unknown;
     }>;
 };
+/**
+ * Approval remotes of this plugin's namespace. Read-only listing plus the one
+ * write: the operator's answer to a parked tool call.
+ */
+export interface QaApprovalApi {
+    pendingApprovals(token: string, sessionId: string): Promise<{
+        readonly ok: true;
+        readonly value: readonly QaPendingApproval[];
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+    answerApproval(token: string, sessionId: string, requestId: string, decision: QaApprovalDecision): Promise<{
+        readonly ok: true;
+        readonly value: boolean;
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+}
+/**
+ * Question remotes of this plugin's namespace: the parked `ask_user_question`
+ * requests of one chat, the operator's answers, and closing one unanswered.
+ */
+export interface QaQuestionApi {
+    pendingQuestions(token: string, sessionId: string): Promise<{
+        readonly ok: true;
+        readonly value: readonly QaPendingQuestion[];
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+    answerQuestion(token: string, sessionId: string, requestId: string, answers: readonly QaQuestionAnswerItem[]): Promise<{
+        readonly ok: true;
+        readonly value: boolean;
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+    cancelQuestion(token: string, sessionId: string, requestId: string): Promise<{
+        readonly ok: true;
+        readonly value: boolean;
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+}
 /** Account remotes exposed by the plugin's own typert namespace. */
 export interface QaAccountsApi {
     accountsWhoami(token: string): Promise<RemoteResult<QaWhoamiResult>>;
@@ -73,6 +146,8 @@ export interface QaAccountsApi {
     accountsListOwnership(token: string): Promise<RemoteResult<{
         readonly entries: readonly QaOwnershipEntry[];
     }>>;
+    /** Replace the caller's own self-declared profile; the token is the identity. */
+    accountsUpdateProfile(token: string, input: QaAccountProfileInput): Promise<RemoteResult<QaAccountUserPublic>>;
 }
 type RemoteResult<Value> = {
     readonly ok: true;

package/lib/types/client/use-right-rail.d.ts

@@ -0,0 +1,56 @@
+import { type Dispatch, type SetStateAction } from "react";
+import type { QaSource, QaTurnSources } from "../types.js";
+import type { QaDrawerCompleteness, QaRailTab } from "./use-session-ui-state.js";
+/**
+ * The rail-related slice of `useSessionUiState`, declared structurally so the
+ * controller consumes exactly what it drives and the rest of the chat-local
+ * state (draft text, variant offsets, the turn mark) stays with the surface.
+ */
+export interface QaRightRailState {
+    readonly railOpen: boolean;
+    readonly setRailOpen: Dispatch<SetStateAction<boolean>>;
+    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 setAgentsOpen: Dispatch<SetStateAction<boolean>>;
+}
+/** What QaSurface reads and hands to the rail, the panels and the header. */
+export interface QaRightRailFacade {
+    readonly railOpen: boolean;
+    readonly railTab: QaRailTab;
+    /** Message-scoped source pin, or null for the whole-chat list. */
+    readonly drawerSources: readonly QaSource[] | null;
+    readonly drawerCompleteness: QaDrawerCompleteness | null;
+    readonly drawerDetail: QaSource | null;
+    /** A message footer's sources control: pin the message-scoped subset. */
+    readonly openSources: (sources: readonly QaSource[], complete: boolean, incompleteOrigins: QaTurnSources["incompleteOrigins"]) => void;
+    /** A message's source chip: show that source's detail instead of a list. */
+    readonly openSourceDetail: (source: QaSource) => void;
+    /** Back to the whole-chat source list, dropping the pin. */
+    readonly showAllSources: () => void;
+    /** Closing the rail also discards the pinned sources, as the drawer did. */
+    readonly close: () => void;
+    /**
+     * The header buttons: a second click on the active tab's button closes the
+     * rail; opening the sources tab shows the full list, dropping any pin.
+     */
+    readonly openTab: (tab: QaRailTab) => void;
+    /** The rail strip's plain tab switch. */
+    readonly selectTab: (tab: QaRailTab) => void;
+    /** The agents drawer and the rail are mutually exclusive; this is its side. */
+    readonly toggleAgents: () => void;
+}
+/**
+ * Right-rail controller over the chat-local drawer state: every transition
+ * between the whole-chat list, a pinned message subset and a single source's
+ * detail lives here, so the surface only wires controls to intents. The
+ * callbacks stay referentially stable — they close over `useState` setters,
+ * whose identities never change.
+ */
+export declare function useRightRail(ui: QaRightRailState): QaRightRailFacade;
+//# sourceMappingURL=use-right-rail.d.ts.map