@yadsh/dsh-qa-surface 0.2.0 → 0.4.0

package/lib/types/account-remotes.d.ts

@@ -0,0 +1,42 @@
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import { QaAccounts } from "./accounts/store.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountUserPublic, QaClaimResult, QaOwnershipEntry, QaWhoamiResult, ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * Host-side bodies of the account remotes the `QaSurface` service exposes.
+ * The `@Remote`-decorated signatures stay on the service class (typert code
+ * generation reads the class shape); this context carries everything behind
+ * them: store construction and memoization, the disabled refusal, and the
+ * error mapping onto the shared `(reason: <code>)` wire marker.
+ */
+export interface QaAccountRemotes {
+    /** The accounts store behind the runtime toggle, or undefined while off. */
+    resolve(config: ResolvedQaSurfaceConfig): QaAccounts | undefined;
+    /** Map a store failure onto the shared `(reason: <code>)` wire marker. */
+    run<T>(operation: () => T, sessionIdForLog?: string): T;
+    register(email: string, password: string): QaAccountSession;
+    login(email: string, password: string): QaAccountSession;
+    /** Identity probe; safe to call with an empty or expired token. */
+    whoami(token: string): QaWhoamiResult;
+    /** Migrate a browser's local chat index into server-side ownership. */
+    claimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
+    /** The token user's owned session ids; the sidebar list authority. */
+    ownedSessions(token: string): {
+        readonly ids: readonly string[];
+    };
+    /**
+     * Every chat-ownership entry with owner display names; the cross-user view
+     * admin browsers group the sidebar by. Ordinary accounts are refused with
+     * the dedicated reason, anonymous ones with auth-required.
+     */
+    listOwnership(token: string): {
+        readonly entries: readonly QaOwnershipEntry[];
+    };
+    /** Replace the caller's own self-declared profile; the token is the identity. */
+    updateProfile(token: string, input: QaAccountProfileInput): QaAccountUserPublic;
+}
+/** Build the account-remotes context for one `QaSurface` service instance. */
+export declare function createQaAccountRemotes(options: {
+    getConfig: () => ResolvedQaSurfaceConfig;
+    logger: PluginLogger;
+}): QaAccountRemotes;
+//# sourceMappingURL=account-remotes.d.ts.map

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

@@ -0,0 +1,14 @@
+/** An account request after normalization, ready to become a stored user. */
+export interface ValidatedCredentials {
+    readonly email: string;
+    /** Trimmed display name; empty means "derive one from the address". */
+    readonly displayName: string;
+}
+/**
+ * The email/password/display-name gate shared by self-registration and the
+ * operator's addUser, so both paths reject unusable input with the same
+ * errors and messages, in the same order. Returns the normalized address and
+ * trimmed display name; the caller still decides uniqueness and role.
+ */
+export declare function validateCredentials(email: string, password: string, displayName: string | undefined): ValidatedCredentials;
+//# sourceMappingURL=credentials.d.ts.map

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/index.d.ts

@@ -0,0 +1,2 @@
+export { QaAccounts, QaAccountsError, defaultAccountsFilePath, type QaAccountsErrorReason, type QaAccountsOptions, } from "./store.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,144 @@
+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[];
+}
+/**
+ * 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;
+    private file;
+    private readonly authAttempts;
+    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 readonly fileStamp;
+    constructor(filePath: string | undefined, options: QaAccountsOptions);
+    /**
+     * 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 save;
+    private pruneAuthAttempts;
+    private assertAuthBudget;
+    private userByEmail;
+    register(email: string, password: string, displayName?: string): QaAccountSession;
+    login(email: string, password: string): QaAccountSession;
+    whoami(token: string): QaWhoamiResult;
+    /** Resolve a token to its user, or null for absent/invalid/expired ones. */
+    verifyToken(token: string): string | null;
+    private mintToken;
+    /** The account behind a token, or an auth-required refusal. */
+    requireUser(token: string): StoredUser;
+    /**
+     * Ownership gate for one session: claim unowned sessions for the requesting
+     * user (first come, first served — the pre-accounts migration path), refuse
+     * 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. */
+    ownedSessionIds(token: string): readonly string[];
+    /**
+     * Every ownership entry with the owner's display name resolved at read
+     * time, oldest claim first. Admin-only: this is the cross-user view the
+     * admin sidebar groups chats by; ordinary accounts get a dedicated refusal.
+     */
+    listOwnership(token: string): readonly QaOwnershipEntry[];
+    /** Every account, file order; for `qa-accounts list`. */
+    listUsers(): readonly {
+        readonly email: string;
+        readonly displayName: string;
+        readonly role: QaAccountRole;
+        readonly disabled: boolean;
+        readonly createdAt: string;
+        readonly lastLoginAt: string | null;
+    }[];
+    /** Create an account outside the self-registration gate. */
+    addUser(email: string, password: string, options?: {
+        displayName?: string;
+        role?: QaAccountRole;
+    }): QaAccountUserPublic;
+    private editUser;
+    /** Grant or revoke the admin role. */
+    setUserRole(email: string, role: QaAccountRole): QaAccountUserPublic;
+    /**
+     * Disable an account: future logins are refused and every live token is
+     * invalidated (the token version bumps). `enable` does not resurrect old
+     * tokens — the account signs in again.
+     */
+    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;
+}
+//# 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/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/attestation.d.ts

@@ -8,7 +8,7 @@
  * audience, precise enough for an operator reading the browser console to
  * know which class of mismatch to look for in the Host logs.
  */
-export type QaAttestationReason = "agent-unavailable" | "workspace-unavailable" | "composition-mismatch" | "permission-preset" | "adoption-refused" | "unknown-tools" | "attestation-failed";
+export type QaAttestationReason = "agent-unavailable" | "workspace-unavailable" | "composition-mismatch" | "permission-preset" | "adoption-refused" | "unknown-tools" | "auth-required" | "session-owned-elsewhere" | "attestation-failed";
 /** Host rejection whose wire message carries the coarse reason marker. */
 export declare class QaAttestationError extends Error {
     readonly reason: QaAttestationReason;

package/lib/types/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export interface CliIo {
+    out(line: string): void;
+    err(line: string): void;
+}
+/** Execute one management command; returns the process exit code. */
+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

@@ -0,0 +1,102 @@
+import type { QaAccountProfileInput, QaAccountUserPublic, QaOwnershipEntry, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaAccountsApi, StorageLike } from "./types.js";
+export type QaAccountsSnapshot = {
+    readonly stage: "checking";
+} | {
+    readonly stage: "gate";
+    readonly mode: "login" | "register";
+    readonly busy: boolean;
+    readonly error: string | null;
+} | {
+    readonly stage: "authed";
+    readonly user: QaAccountUserPublic;
+    /**
+     * Server-known chat ids; the sidebar list authority. Own chats always,
+     * plus every mapped chat for an admin (the cross-user grouping view).
+     */
+    readonly ownedIds: readonly string[];
+    /**
+     * The full ownership map; admins only, empty for ordinary accounts and
+     * whenever the admin listing was refused or unavailable.
+     */
+    readonly ownership: readonly QaOwnershipEntry[];
+    /** Bumped whenever ownedIds or ownership changes; re-projects lists. */
+    readonly ownedRevision: number;
+};
+/**
+ * Audience-safe copy for the coarse account refusal codes; anything unknown
+ * falls back to the generic line.
+ */
+export declare function accountsErrorMessage(code: string | null): string;
+/** Extract the coarse account reason code from a Host wire failure. */
+export declare function accountsReasonOf(failure: unknown): string | null;
+export interface QaAccountsControllerOptions {
+    readonly remote: QaAccountsApi;
+    readonly storage: StorageLike | undefined;
+    /** Config snapshot getter; the token key follows the deployment identity. */
+    readonly config: () => ResolvedQaSurfaceConfig;
+    /**
+     * The legacy per-browser chat index at login time, for the one-shot
+     * ownership migration; conflicts are dropped through {@link forgetChat}.
+     */
+    readonly legacyChatIds?: () => readonly string[];
+    readonly forgetChat?: (sessionId: string) => void;
+}
+/**
+ * Browser-side account lifecycle: token persistence, the checking → gate →
+ * authed state machine, and the ownership bookkeeping the sidebar list is
+ * built from. Anonymous/failed identity never blocks a deployment with
+ * accounts disabled — the caller simply does not mount this controller.
+ */
+export declare class QaAccountsController {
+    private readonly options;
+    private readonly listeners;
+    private snapshot;
+    private tokenValue;
+    private disposed;
+    constructor(options: QaAccountsControllerOptions);
+    getSnapshot: () => QaAccountsSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    dispose(): void;
+    /** The bearer token threaded into gated remotes; null while anonymous. */
+    /** The bearer token threaded into gated remotes; null while anonymous. */
+    token(): string | null;
+    /** Server-owned chat ids (empty until authed); falls back to nothing. */
+    ownedIds(): readonly string[];
+    /** Boot probe: restore the stored token and ask the Host who it is. */
+    start(): Promise<void>;
+    login(email: string, password: string): Promise<void>;
+    register(email: string, password: string): Promise<void>;
+    setMode(mode: "login" | "register"): void;
+    /** Drop the token and return to the gate (logout or expired identity). */
+    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;
+    /** Refresh the owned list after index changes; cheap enough to re-pull. */
+    refreshOwned(): Promise<void>;
+    /** The admin cross-user ownership view; failures degrade to an empty map. */
+    private fetchOwnership;
+    /** Session id → owner display name; empty unless an admin is signed in. */
+    ownerNames(): ReadonlyMap<string, string>;
+    /**
+     * The chat owner's display name for author labels: admins see it on
+     * foreign chats only; the owner themself and ordinary accounts see none.
+     */
+    messageAuthorOf(sessionId: string): string | undefined;
+    private readStoredToken;
+    private saveStoredToken;
+    private clearStoredToken;
+    private tokenKey;
+    private publish;
+}
+//# sourceMappingURL=QaAccountsController.d.ts.map

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

@@ -1,4 +1,4 @@
-import type { SettingsScope } from "@deepseek-ai/dsh-client-runtime/client";
+import type { SettingsScope } from "@deepseek-ai/dsh-client-ui-settings/client";
 import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
 export interface QaConfigSnapshot {
     readonly status: "loading" | "ready" | "unavailable" | "error";

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

@@ -1,13 +1,39 @@
-import type { HostDescriptionSource } from "@deepseek-ai/dsh-client-connection/client";
-import type { QaImageDraft, QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
-import type { QaSecureSession, QaSessions, QaSessionsApi, StorageLike } from "./types.js";
+import type { ConnectionGenerationState } from "@deepseek-ai/dsh-client-connection/client";
+import type { QaAttachmentDraft, QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaConversation, QaCreateSession, QaFileUpload, QaSecureSession, QaSessions, QaSessionsApi, QaSourceApi, StorageLike } from "./types.js";
+export interface QaAccountsFacade {
+    /** The account bearer token, or null while anonymous. */
+    readonly token: () => string | null;
+    /** Server-owned chat ids; the list authority while accounts are on. */
+    readonly ownedIds: () => readonly string[];
+    /**
+     * The chat owner's display name for author labels; admins see it on
+     * foreign chats only, everyone else gets undefined.
+     */
+    readonly messageAuthorOf: (sessionId: string) => string | undefined;
+    /** Called after a new chat binds, so ownership stays current. */
+    readonly onSessionCreated: (sessionId: string) => void;
+    /** Called when the Host refuses with auth-required (expired/rotated). */
+    readonly onAuthRequired: () => void;
+}
 export interface QaSessionControllerOptions {
     readonly sessions: QaSessions;
     readonly api: QaSessionsApi;
-    readonly connection: HostDescriptionSource;
+    readonly createSession: QaCreateSession;
+    /** Conversation assembly feeding the transcript projection. */
+    readonly conversation: QaConversation;
+    readonly connection: ConnectionGenerationState;
     readonly config: ResolvedQaSurfaceConfig;
     readonly secureSession: QaSecureSession;
+    readonly sourceApi?: QaSourceApi;
     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;
     /**
      * Minimum spacing between projections of a running turn's stream frames.
@@ -25,16 +51,26 @@ 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;
     private readonly secureSessionRemote;
+    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;
     private unsubscribeSession;
+    private unsubscribeChat;
     private readonly unsubscribeConnection;
     private ensuring;
     private materializing;
@@ -42,7 +78,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;
@@ -50,11 +85,13 @@ export declare class QaSessionController {
     private disposed;
     private generation;
     private chatsRevision;
+    /** Host-side provenance of the bound chat, merged into the projection. */
+    private readonly hostSources;
     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
@@ -93,15 +130,19 @@ export declare class QaSessionController {
     viewSubagent(id: string, title: string): Promise<void>;
     /** Leave the subagent transcript and re-open the chat it was launched from. */
     closeSubagent(): Promise<void>;
-    /** This browser's indexed chat ids, most recently used first. */
+    /** This browser's chat ids: the owned list when accounts are on, else the
+     * local index. Both intersect the host session list at projection time. */
     chatIds(): readonly string[];
     /** The bound session id, or null while no chat is bound. */
     activeSessionId(): string | null;
     /**
      * Resolve one durable image attachment of the bound session into a
-     * browser-usable URL. The caller caches; failures surface as broken views.
+     * browser-usable URL. Resolutions are cached per chat in the asset
+     * repository (attachment ids repeat across chats) and revoked when the chat
+     * is unbound; failures surface as broken views and retry on demand.
      */
     readImage(attachmentId: string): Promise<string>;
+    private readAttachmentUrl;
     /**
      * Remove one chat from this browser's index. Deleting the chat that is
      * currently open also forgets the persisted id and starts a fresh attested
@@ -120,26 +161,24 @@ export declare class QaSessionController {
      * re-opening re-materializes it. Step 2 — when that refused session is
      * still blank (it never received the prompt, so there is nothing to lose) —
      * starts a fresh attested session instead. A session with history is left
-     * alone: recreating it would silently drop the conversation.
+     * alone: recreating it would silently drop the conversation. Returns the
+     * attested session id, or null when nothing was attested.
      */
     private recoverForSend;
-    private createSession;
     private bind;
     private unbind;
     private waitForConnection;
-    /**
-     * Project one session notification. A running turn's frames arrive at
-     * animation-frame cadence, so re-projections are spaced at least
-     * {@link streamIntervalMs} apart: the first frame of a window projects at
-     * once and further frames are absorbed (the memoized render path replays
-     * nothing, so absorbing a frame only defers it). Everything outside a
-     * running turn - phase flips, errors, turn completion - projects
-     * immediately.
-     */
+    /** 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;
+    /**
+     * Attest the currently bound session. `ok` carries the session id the proof
+     * was issued for; `stale` means the binding changed while the request was
+     * in flight, so nothing was written — the newer binding manages its own
+     * attestation; `refused` is a genuine admission refusal of this binding.
+     */
     private attestPolicy;
     private emit;
 }