@yadsh/dsh-qa-surface 0.3.0 → 0.5.0

package/lib/types/accounts/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Coarse, wire-safe account failure codes. They ride the `(reason: <code>)`
+ * marker pattern the attestation path established; the browser maps them to
+ * audience-safe copy and the precise cause stays in the Host logs.
+ */
+export type QaAccountsErrorReason = "auth-required" | "admin-required" | "invalid-credentials" | "account-disabled" | "email-taken" | "invalid-email" | "invalid-display-name" | "invalid-profile" | "profile-disabled" | "invalid-role" | "weak-password" | "registration-disabled" | "rate-limited" | "session-owned-elsewhere";
+export declare class QaAccountsError extends Error {
+    readonly reason: QaAccountsErrorReason;
+    constructor(reason: QaAccountsErrorReason, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/lib/types/accounts/file.d.ts

@@ -0,0 +1,82 @@
+import type { Stats } from "node:fs";
+import type { QaAccountRole } from "../types.js";
+/** One account's self-declared profile as it rests in the accounts file. */
+export interface StoredProfile {
+    fullName?: string;
+    identities?: Record<string, string>;
+    instructions?: string;
+    updatedAt?: string;
+}
+export interface StoredUser {
+    readonly id: string;
+    readonly email: string;
+    readonly displayName: string;
+    readonly role: QaAccountRole;
+    /** scrypt material: hex salt + hex hash. */
+    readonly passwordHash: {
+        readonly salt: string;
+        readonly hash: string;
+    };
+    readonly createdAt: string;
+    lastLoginAt: string | null;
+    /** Disabled accounts are refused at login and lose their live tokens. */
+    disabled?: boolean;
+    /**
+     * Bumped to invalidate every token ever issued to the account: the value
+     * rides the token payload and must match at verification time.
+     */
+    tokenVersion?: number;
+    /** Absent until the owner fills the profile form for the first time. */
+    profile?: StoredProfile;
+}
+export interface AccountsFile {
+    readonly version: 1;
+    /** HMAC key for account tokens; rotated on password change by rewriting it. */
+    readonly secret: string;
+    readonly users: StoredUser[];
+    readonly ownership: Record<string, {
+        readonly userId: string;
+        readonly claimedAt: string;
+    }>;
+}
+/** mtime+size pair identifying one on-disk version of the accounts file. */
+export interface FileStamp {
+    readonly mtimeMs: number;
+    readonly size: number;
+}
+/**
+ * Where the last-seen stamp lives. Load and persist keep it current in place,
+ * so a caller holds one mutable ref instead of threading the stamp through
+ * every read-modify-write.
+ */
+export interface FileStampRef {
+    current: FileStamp;
+}
+/** A stamp no real file can match, so the first load always reads the disk. */
+export declare function createFileStampRef(): FileStampRef;
+export declare function stampOf(stat: Stats): FileStamp;
+/** The accounts file lives next to the DSH home the launcher exports. */
+export declare function defaultAccountsFilePath(): string;
+/**
+ * Read the accounts file, or create it on first run with a fresh token
+ * secret. The stamp ref is left pointing at the version just read.
+ */
+export declare function loadAccountsFile(filePath: string, stamp: FileStampRef): AccountsFile;
+/**
+ * Persist the accounts file atomically (temp file + rename) and leave the
+ * stamp ref pointing at the freshly written version.
+ */
+export declare function persistAccountsFile(filePath: string, file: AccountsFile, stamp: FileStampRef): void;
+/**
+ * The qa-accounts CLI runs in its own process against the same file. Re-read
+ * it whenever it changed on disk, before every read or read-modify-write:
+ * without this a running Host would keep honoring tokens the CLI revoked
+ * and its next save would resurrect the CLI's change from a stale snapshot.
+ * One file, one writer at a time remains the deployment's discipline; LAN
+ * scale keeps the stat per operation trivial.
+ *
+ * Returns the freshly loaded file, or undefined when the caller should keep
+ * serving its in-memory state.
+ */
+export declare function reloadAccountsFileIfChanged(filePath: string, stamp: FileStampRef): AccountsFile | undefined;
+//# sourceMappingURL=file.d.ts.map

package/lib/types/accounts/store.d.ts

@@ -1,46 +1,30 @@
-import type { QaAccountRole, QaAccountSession, QaAccountUserPublic, QaClaimResult, QaOwnershipEntry, QaWhoamiResult } from "../types.js";
-/**
- * Coarse, wire-safe account failure codes. They ride the `(reason: <code>)`
- * marker pattern the attestation path established; the browser maps them to
- * audience-safe copy and the precise cause stays in the Host logs.
- */
-export type QaAccountsErrorReason = "auth-required" | "admin-required" | "invalid-credentials" | "account-disabled" | "email-taken" | "invalid-email" | "invalid-display-name" | "invalid-role" | "weak-password" | "registration-disabled" | "rate-limited" | "session-owned-elsewhere";
-export declare class QaAccountsError extends Error {
-    readonly reason: QaAccountsErrorReason;
-    constructor(reason: QaAccountsErrorReason, message: string);
-}
-interface StoredUser {
-    readonly id: string;
-    readonly email: string;
-    readonly displayName: string;
-    readonly role: QaAccountRole;
-    /** scrypt material: hex salt + hex hash. */
-    readonly passwordHash: {
-        readonly salt: string;
-        readonly hash: string;
-    };
-    readonly createdAt: string;
-    lastLoginAt: string | null;
-    /** Disabled accounts are refused at login and lose their live tokens. */
-    disabled?: boolean;
-    /**
-     * Bumped to invalidate every token ever issued to the account: the value
-     * rides the token payload and must match at verification time.
-     */
-    tokenVersion?: number;
-}
+import type { QaAccountIdentityField, QaAccountProfile, QaAccountProfileInput, QaAccountRole, QaAccountSession, QaAccountUserPublic, QaClaimResult, QaOwnershipEntry, QaWhoamiResult } from "../types.js";
+import type { StoredUser } from "./file.js";
+export { QaAccountsError } from "./errors.js";
+export type { QaAccountsErrorReason } from "./errors.js";
+export { defaultAccountsFilePath } from "./file.js";
 export interface QaAccountsOptions {
     readonly sessionTtlDays: number;
     readonly allowRegistration: boolean;
     /** Login/registration attempts accepted per rolling minute, store-wide. */
     readonly maxAuthAttemptsPerMinute?: number;
+    /** Character cap on a stored profile's agent guidance. */
+    readonly instructionsMaxLength?: number;
+    /**
+     * Fields the deployment declares. Self-service writes may name only these;
+     * omitting the list (the operator CLI) checks the key shape alone.
+     */
+    readonly identityFields?: readonly QaAccountIdentityField[];
 }
-/** The accounts file lives next to the DSH home the launcher exports. */
-export declare function defaultAccountsFilePath(): string;
 /**
  * Host authority for QA accounts: the file-backed user list, the session
  * ownership map and the HMAC account tokens. All mutations are synchronous
  * and persisted atomically (temp file + rename); LAN scale keeps this trivial.
+ *
+ * The class is the facade: token mechanics live in token.ts, the file format
+ * and its atomic persistence plus the external-change probe in file.ts, and
+ * the credential rules shared by registration and the operator CLI in
+ * credentials.ts.
  */
 export declare class QaAccounts {
     readonly filePath: string;
@@ -49,20 +33,19 @@ export declare class QaAccounts {
     private readonly maxAuthAttemptsPerMinute;
     private readonly sessionTtlDays;
     private readonly allowRegistration;
+    /** Character cap on a stored profile's agent guidance. */
+    private readonly instructionsMaxLength;
+    /** Declared handle fields; undefined lets an operator write any shape-valid key. */
+    private readonly identityFields;
     /** mtime+size of the file as of the last load; the external-change probe. */
-    private lastLoadStamp;
+    private readonly fileStamp;
     constructor(filePath: string | undefined, options: QaAccountsOptions);
     /**
-     * The qa-accounts CLI runs in its own process against the same file. Re-read
-     * it whenever it changed on disk, before every read or read-modify-write:
-     * without this a running Host would keep honoring tokens the CLI revoked
-     * and its next save would resurrect the CLI's change from a stale snapshot.
-     * One file, one writer at a time remains the deployment's discipline; LAN
-     * scale keeps the stat per operation trivial.
+     * Re-read the accounts file when it changed on disk, before every read or
+     * read-modify-write. The probe itself and its cross-process rationale live
+     * with the file layer (reloadAccountsFileIfChanged).
      */
     private reloadIfChanged;
-    private load;
-    private persist;
     private save;
     private pruneAuthAttempts;
     private assertAuthBudget;
@@ -81,6 +64,14 @@ export declare class QaAccounts {
      * foreign sessions unless the caller administers the deployment.
      */
     ensureSessionAccess(token: string, sessionId: string): QaAccountUserPublic;
+    /**
+     * Atomically reserve a Host-generated session id for the token user before
+     * the Session exists. Browser callers therefore never get a race window in
+     * which they can claim another user's newly created chat.
+     */
+    reserveSession(token: string, sessionId: string): QaAccountUserPublic;
+    /** Roll back a reservation if Host creation failed before a chat existed. */
+    releaseSessionReservation(userId: string, sessionId: string): void;
     /** Bulk-claim a browser's local chat index; foreign ids come back as conflicts. */
     claimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
     /** Session ids owned by the token's user, most recently claimed first. */
@@ -108,6 +99,14 @@ export declare class QaAccounts {
     private editUser;
     /** Grant or revoke the admin role. */
     setUserRole(email: string, role: QaAccountRole): QaAccountUserPublic;
+    /**
+     * Replace an account's password, which is what a forgotten one needs. The
+     * token version bumps with it, so every token minted under the old password
+     * dies server-side: a reset is also the response to a leaked credential.
+     * Ownership, profile and the account id survive, so the user's chats are
+     * still theirs after signing in again.
+     */
+    setPassword(email: string, password: string): QaAccountUserPublic;
     /**
      * Disable an account: future logins are refused and every live token is
      * invalidated (the token version bumps). `enable` does not resurrect old
@@ -116,6 +115,38 @@ export declare class QaAccounts {
     setUserDisabled(email: string, disabled: boolean): QaAccountUserPublic;
     /** Invalidate every token of the account (password-leak response). */
     revokeTokens(email: string): QaAccountUserPublic;
+    /**
+     * The account that owns one session, or undefined while nobody claimed it.
+     * The prompt renderer resolves a chat's owner through this map, so a session
+     * that predates accounts simply carries no identity.
+     */
+    ownerIdOf(sessionId: string): string | undefined;
+    /**
+     * Email plus profile of one account, for the prompt renderer. A disabled
+     * account resolves to nothing: its identity leaves the prompt together with
+     * its access, so a revoked user is no longer addressed by name.
+     */
+    identityOf(userId: string): {
+        readonly email: string;
+        readonly profile: QaAccountProfile;
+    } | undefined;
+    /** One account in its public shape; undefined when the address is unknown. */
+    findUser(email: string): QaAccountUserPublic | undefined;
+    /**
+     * Operator write: replace one account's profile, addressed by email. The
+     * CLI merges field-level flags into a full profile before calling this.
+     */
+    setProfile(email: string, input: QaAccountProfileInput): QaAccountUserPublic;
+    /**
+     * Self-service write for the token's own account. The token is verified
+     * first, so a browser can only ever edit the profile it is signed in as.
+     */
+    updateOwnProfile(token: string, input: QaAccountProfileInput): QaAccountUserPublic;
+    /**
+     * Validate one profile write and stamp it onto the account. Throws before
+     * anything is mutated, so a rejected write leaves the stored profile, and
+     * the address it is keyed to, exactly as they were.
+     */
+    private stampedProfile;
 }
-export {};
 //# sourceMappingURL=store.d.ts.map

package/lib/types/accounts/token.d.ts

@@ -0,0 +1,31 @@
+/** The account facts token verification needs: identity plus token version. */
+interface TokenUser {
+    readonly id: string;
+    readonly tokenVersion?: number;
+}
+/** The claims carried by a v1 account token payload. */
+export interface TokenPayload {
+    readonly uid: string;
+    /** Expiry, epoch milliseconds. */
+    readonly exp: number;
+    /** The account's token version at mint time. */
+    readonly ver: number;
+}
+export declare function base64Url(value: Buffer | string): string;
+/**
+ * Mint a v1 account token: a base64url JSON payload plus an HMAC-SHA256
+ * signature keyed with the accounts file secret.
+ */
+export declare function mintToken(secret: string, payload: TokenPayload): string;
+/**
+ * Verify a v1 account token against the current secret and account list and
+ * return its user id, or null for anything malformed, foreign-signed,
+ * expired or superseded. Signature computation, the length check and the
+ * payload decode share one try, so a hostile token can only ever resolve to
+ * null; the comparison is timing-safe (equal length first, then
+ * timingSafeEqual) so a signature guess cannot be accelerated by measuring
+ * HMAC rejection time.
+ */
+export declare function verifyToken(secret: string, token: string, users: readonly TokenUser[]): string | null;
+export {};
+//# sourceMappingURL=token.d.ts.map

package/lib/types/approvals.d.ts

@@ -0,0 +1,65 @@
+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 { QaApprovalDecision, QaPendingApproval } from "./types.js";
+/**
+ * The slice of the `tools/pre-execute` execution record this gate reads. The
+ * listener is owned by the plugin context, so it is unfiltered: it also wraps
+ * the calls of a delegated child, whose scope chain never reaches the chat's
+ * own agent context.
+ */
+export interface QaApprovalExecution {
+    readonly name: string;
+    readonly agent?: Agent;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Interactive resolution of the tool policy `ask` decision.
+ *
+ * A composed gate — a content classifier, a hook rule — answers `ask` for a
+ * call it will not decide alone. On an attested QA agent that ask resolves
+ * against the deployment's pinned `approval=never` policy, so the model is told
+ * the user rejected a call the user never saw. This gate sits outside every
+ * other `tools/pre-execute` listener and hands the decision to the operator
+ * instead: the request is parked here, the QA view lists it over its own
+ * remote, and the answer becomes the decision the chain would have produced.
+ *
+ * `interaction.approvals: blocked` keeps the previous fail-closed behavior —
+ * the call is refused with the surface's own reason. Either way nothing is
+ * approved automatically, and the allow-list, the workspace fence and the
+ * read-only sandbox still run on the resolved call.
+ *
+ * Only sessions this deployment attested are touched. Any other session's ask
+ * is handed back to the chain untouched, so an operator instance that also
+ * serves ordinary chats keeps its own approval flow.
+ */
+export declare class QaApprovalGate {
+    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);
+    /** Wrap every tool call; other gates compose inside this listener. */
+    install(): void;
+    /** Approvals of one chat, oldest first: what the QA view lists. */
+    list(sessionId: string): readonly QaPendingApproval[];
+    /** Apply the operator's answer; an unknown or foreign id is refused. */
+    answer(sessionId: string, requestId: string, decision: QaApprovalDecision): boolean;
+    /** Detach the listener and fail every parked request. Wired as an effect. */
+    dispose(): void;
+    private handle;
+    /**
+     * The chat a call belongs to, when this deployment attested it. A child of an
+     * attested chat answers under the chat the operator is looking at.
+     */
+    private ownerOf;
+    /** Park one call until the operator answers, the turn is cancelled, or … */
+    private request;
+    private resolve;
+    /** Fail the requests one session's agent owns; a child never holds the chat. */
+    private settleOwner;
+}
+//# sourceMappingURL=approvals.d.ts.map

package/lib/types/attachment-rules.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Attachment vocabulary shared by the Host configuration and the browser
+ * composer. The module stays free of Node and DOM imports: the client bundle
+ * imports it directly, and the Host resolver uses it to normalize the
+ * operator's configuration.
+ */
+/**
+ * Text-file extensions the composer accepts out of the box. Compared
+ * lowercase and without the leading dot; an entry is a suffix, not a glob.
+ */
+export declare const DEFAULT_QA_TEXT_EXTENSIONS: readonly string[];
+/** Bounds the resolver and the settings card agree on. */
+export declare const QA_PASTED_TEXT_LINES_MIN = 0;
+export declare const QA_PASTED_TEXT_LINES_MAX = 10000;
+export declare const QA_MAX_FILE_BYTES_MIN = 1024;
+export declare const QA_MAX_FILE_BYTES_MAX = 52428800;
+export declare const QA_MAX_PENDING_MIN = 1;
+export declare const QA_MAX_PENDING_MAX = 40;
+/**
+ * Normalize an operator-authored extension list: lowercase, leading dots
+ * stripped, malformed entries and duplicates dropped, order preserved.
+ * An empty result means no extension is accepted by name — the composer then
+ * still accepts whatever the browser reports as `text/*`.
+ * @param values - raw extension tokens from configuration.
+ * @returns the normalized token list.
+ */
+export declare function normalizeTextExtensions(values: readonly string[]): readonly string[];
+/**
+ * Whether one file name carries an accepted text extension. The comparison is
+ * case-insensitive; a name without a dot, or with a hidden-file dot only
+ * (`.gitignore`), is matched against the whole leaf.
+ * @param name - display file name.
+ * @param extensions - normalized accepted extensions.
+ * @returns whether the name matches one accepted extension.
+ */
+export declare function hasTextExtension(name: string, extensions: readonly string[]): boolean;
+/**
+ * Count the lines of a pasted blob the way a reader counts them: a single
+ * trailing newline does not open a new line, and CRLF counts once.
+ * @param text - pasted plain text.
+ * @returns the line count, at least 1 for any non-empty text.
+ */
+export declare function countTextLines(text: string): number;
+//# sourceMappingURL=attachment-rules.d.ts.map

package/lib/types/cli.d.ts

@@ -4,6 +4,6 @@ export interface CliIo {
     err(line: string): void;
 }
 /** Execute one management command; returns the process exit code. */
-export declare function run(argv: readonly string[], io: CliIo, readPassword?: () => string): number;
-export declare function main(argv: readonly string[], io?: CliIo, readPassword?: () => string): number;
+export declare function run(argv: readonly string[], io: CliIo, readStdin?: () => string): number;
+export declare function main(argv: readonly string[], io?: CliIo, readStdin?: () => string): number;
 //# sourceMappingURL=cli.d.ts.map

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

@@ -1,4 +1,4 @@
-import type { QaAccountUserPublic, QaOwnershipEntry, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaAccountProfileInput, QaAccountUserPublic, QaOwnershipEntry, ResolvedQaSurfaceConfig } from "../types.js";
 import type { QaAccountsApi, StorageLike } from "./types.js";
 export type QaAccountsSnapshot = {
     readonly stage: "checking";
@@ -72,6 +72,13 @@ export declare class QaAccountsController {
     signOut(): void;
     /** Claim one freshly created chat so the ownership map stays current. */
     claimNewSession(sessionId: string): Promise<void>;
+    /**
+     * Replace the signed-in user's own profile. Resolves to audience-safe
+     * refusal copy when the Host rejected the write, and to null once the
+     * snapshot carries the stored profile — the form reports the outcome inline
+     * rather than through the gate's state machine.
+     */
+    updateProfile(input: QaAccountProfileInput): Promise<string | null>;
     private authenticate;
     /** Own the account, migrate the legacy index, then project authed. */
     private enterSession;

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

@@ -1,6 +1,7 @@
 import type { ConnectionGenerationState } from "@deepseek-ai/dsh-client-connection/client";
-import type { QaImageDraft, QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
-import type { QaConversation, QaSecureSession, QaSessions, QaSessionsApi, QaSourceApi, StorageLike } from "./types.js";
+import type { QaAttachmentDraft, QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaApprovalApi, QaConversation, QaCreateSession, QaFileUpload, QaSecureSession, QaSessions, QaSessionsApi, QaQuestionApi, QaSourceApi, StorageLike } from "./types.js";
+import type { QaApprovalDecision, QaQuestionAnswerItem } from "../types.js";
 export interface QaAccountsFacade {
     /** The account bearer token, or null while anonymous. */
     readonly token: () => string | null;
@@ -19,13 +20,30 @@ export interface QaAccountsFacade {
 export interface QaSessionControllerOptions {
     readonly sessions: QaSessions;
     readonly api: QaSessionsApi;
+    readonly createSession: QaCreateSession;
     /** Conversation assembly feeding the transcript projection. */
     readonly conversation: QaConversation;
     readonly connection: ConnectionGenerationState;
     readonly config: ResolvedQaSurfaceConfig;
     readonly secureSession: QaSecureSession;
     readonly sourceApi?: QaSourceApi;
+    /**
+     * The approval half of the Host namespace. Absent on a page built against a
+     * Host that does not answer approvals: the surface then never shows a
+     * request and keeps the composer as it is.
+     */
+    readonly approvalApi?: QaApprovalApi;
+    /**
+     * The question half of the Host namespace. Absent on a page whose Host build
+     * does not answer questions: the surface then only renders what it can.
+     */
+    readonly questionApi?: QaQuestionApi;
     readonly storage?: StorageLike;
+    /**
+     * Browser file-upload service, resolved lazily: the page may not serve the
+     * upload plugin, and a deployment without it keeps images and text only.
+     */
+    readonly fileUpload?: () => QaFileUpload | undefined;
     /** Present while the deployment gates QA users with accounts. */
     readonly accounts?: QaAccountsFacade;
     readonly timeoutMs?: number;
@@ -45,7 +63,7 @@ export interface QaSessionControllerOptions {
 export declare class QaSessionController {
     private readonly listeners;
     private readonly sessions;
-    private readonly api;
+    private readonly createSessionRemote;
     private readonly conversation;
     private readonly connection;
     private readonly config;
@@ -53,10 +71,13 @@ export declare class QaSessionController {
     private readonly sourceApi;
     private readonly chats;
     private readonly accounts;
+    /** Resolved per send: a page without the upload plugin has no receipts. */
+    private readonly fileUpload;
     /** Per-chat attachment URL cache; blob URLs die with the chat binding. */
     private readonly assets;
     private readonly timeoutMs;
-    private readonly streamIntervalMs;
+    /** Spacing for a running turn's stream frames; the policy lives there. */
+    private readonly streamPublisher;
     private state;
     private session;
     private conversationBinding;
@@ -69,7 +90,6 @@ export declare class QaSessionController {
     private admissionPending;
     private policyReady;
     private drafting;
-    private streamFlushTimer;
     /** The chat session to return to when a subagent view closes. */
     private chatSessionId;
     private viewingSubagent;
@@ -79,11 +99,17 @@ export declare class QaSessionController {
     private chatsRevision;
     /** Host-side provenance of the bound chat, merged into the projection. */
     private readonly hostSources;
+    /** Host-side approvals of the bound chat waiting for the operator. */
+    private readonly hostApprovals;
+    /** Host-side question requests of the bound chat waiting for the operator. */
+    private readonly hostQuestions;
+    /** Set while a running turn is polled for parked requests. */
+    private pendingTimer;
     constructor(options: QaSessionControllerOptions);
     getSnapshot: () => QaSessionState;
     subscribe: (listener: () => void) => (() => void);
     ensureSession(): Promise<void>;
-    send(text: string, images?: readonly QaImageDraft[]): Promise<boolean>;
+    send(text: string, attachments?: readonly QaAttachmentDraft[]): 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
@@ -160,17 +186,9 @@ export declare class QaSessionController {
     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.
-     */
+    /** Project one session notification; the running-turn spacing policy
+     * (first frame at once, further frames absorbed) lives in the publisher. */
     private publishSessionUpdate;
-    private clearStreamFlush;
     private publish;
     private fail;
     /**
@@ -181,5 +199,24 @@ export declare class QaSessionController {
      */
     private attestPolicy;
     private emit;
+    /**
+     * Answer a request the Host parked for this chat. The Host re-checks the
+     * request against the chat, so an answer that lost its race is a no-op; the
+     * refresh that follows is what the surface renders.
+     */
+    answerApproval(requestId: string, decision: QaApprovalDecision): Promise<void>;
+    /** Send the operator's answers to one parked question request. */
+    answerQuestion(requestId: string, answers: readonly QaQuestionAnswerItem[]): Promise<void>;
+    /** Close a parked question request without answering it. */
+    cancelQuestion(requestId: string): Promise<void>;
+    /**
+     * Poll the Host for parked requests while a turn runs. A request only exists
+     * inside an open turn, and it is Host state: polling is how the page learns
+     * about it, and how it reappears after a reload. One timer serves both seams,
+     * and each is polled only where the deployment answers it.
+     */
+    private syncPendingPolling;
+    private stopPendingPolling;
+    private hostToken;
 }
 //# sourceMappingURL=QaSessionController.d.ts.map

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

@@ -3,7 +3,7 @@ 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 { QaAccountsController } from "./QaAccountsController.js";
-import type { QaConversation, QaSecureSession, QaSessions, QaSessionsApi, QaSourceApi } from "./types.js";
+import type { QaApprovalApi, QaConversation, QaCreateSession, QaFileUpload, QaSecureSession, QaSessions, QaSessionsApi, QaQuestionApi, QaSourceApi } from "./types.js";
 export interface QaSurfaceFace {
     readonly route: QaRouteController;
     readonly config: QaConfigController;
@@ -12,7 +12,20 @@ export interface QaSurfaceFace {
     readonly api: QaSessionsApi;
     readonly connection: ConnectionGenerationState;
     readonly secureSession: QaSecureSession;
+    readonly createSession: QaCreateSession;
     readonly sourceApi: QaSourceApi;
+    /**
+     * Approval half of the plugin's namespace. Absent on a page whose Host build
+     * does not answer it; the surface then only blocks sends it cannot attest.
+     */
+    readonly approvalApi?: QaApprovalApi;
+    /** Question half of the plugin's namespace, when the Host answers it. */
+    readonly questionApi?: QaQuestionApi;
+    /**
+     * Browser file-upload service, when the page serves the upload plugin.
+     * Resolved per send so a page that loads it later still gets file support.
+     */
+    readonly fileUpload?: () => QaFileUpload | undefined;
     /** Present when the deployment mounts the QA account gate. */
     readonly accounts?: QaAccountsController;
 }

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

@@ -0,0 +1,39 @@
+import type { QaApprovalDecision, QaPendingApproval } from "../types.js";
+import type { QaApprovalApi } from "./types.js";
+/**
+ * The operator's side of a parked tool call.
+ *
+ * A composed gate's `ask` is answered on the Host, so the waiting request is
+ * Host state: it survives a page reload, and the surface learns about it by
+ * asking rather than by receiving an event. The bridge holds the last list it
+ * saw, refreshes it while a turn runs, and forwards an answer.
+ */
+export declare class QaHostApprovalBridge {
+    private readonly approvalApi;
+    private approvals;
+    private signature;
+    private refreshing;
+    private answering;
+    /** Bumped on reset so a stale in-flight response never lands. */
+    private generation;
+    constructor(approvalApi: QaApprovalApi | undefined);
+    /** Leave the chat: a chat switch drops the previous chat's requests. */
+    reset(): void;
+    /** The last list this bridge saw; empty when the deployment blocks them. */
+    list(): readonly QaPendingApproval[];
+    /** Whether this page can ask the Host about approvals at all. */
+    get available(): boolean;
+    /**
+     * Re-read the chat's pending requests; a changed list republishes through the
+     * callback. Overlapping calls coalesce, and a response that outlives its chat
+     * is dropped.
+     */
+    refresh(sessionId: string, token: string, onChanged: () => void): Promise<void>;
+    /**
+     * Answer one request and re-read the list. A refusal is not an error: the
+     * request was already settled (the turn was stopped, the call went away), so
+     * the refresh — not the answer — is what the surface shows.
+     */
+    answer(sessionId: string, token: string, requestId: string, decision: QaApprovalDecision): Promise<void>;
+}
+//# sourceMappingURL=approvals.d.ts.map