@yadsh/dsh-qa-surface 0.3.0 → 0.5.0

package/lib/types/shared/session-key.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The browser-local key namespace every QA-side index derives from: the
+ * configured storage key pinned to the served route, versioned once so the
+ * Host's head-script injection and the client bundle cannot drift apart.
+ *
+ * Dependency-free like every `src/shared` module: both bundles inline it.
+ */
+/**
+ * The versioned key prefix for browser-local QA state of one deployment.
+ * Callers append their own scope suffix (`:account-token`, `:welcome-notice`,
+ * `:chat:<id>`, …).
+ * @param config - configuration holding the storage key and the route path.
+ * @returns the versioned prefix, e.g. `dsh-qa-surface.session:v1:/qa`.
+ */
+export declare function qaStorageNamespace(config: Readonly<{
+    session: {
+        storageKey: string;
+    };
+    route: {
+        path: string;
+    };
+}>): string;
+//# sourceMappingURL=session-key.d.ts.map

package/lib/types/shared/settings.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Identity shared by the Host plugin and its browser settings card.
+ *
+ * This module must stay dependency-free: the card bundle inlines it, and a
+ * browser build must not pull the Host config surface (schemastery) into the
+ * page just to learn the namespace name.
+ */
+/** Settings namespace the QA surface owns and its card binds to. */
+export declare const QA_SURFACE_SETTINGS_NAMESPACE = "qa-surface";
+//# sourceMappingURL=settings.d.ts.map

package/lib/types/thinking-phrases.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Phrases the running indicator cycles through. The list deliberately mixes
+ * Russian idiom with workshop imagery: a turn that keeps reshuffling the same
+ * thought in new words reads as alive, while a frozen one reads as stuck.
+ *
+ * Operators replace the list through `thinkingPhrases`; this module holds the
+ * canonical default so the config schema, the resolver and the browser all
+ * read one list.
+ */
+export declare const DEFAULT_THINKING_PHRASES: readonly string[];
+/**
+ * Phrase shown `elapsedMs` into a running turn. The list is operator supplied,
+ * so an empty one falls back to the default: the indicator always needs a
+ * label.
+ */
+export declare function thinkingPhrase(elapsedMs: number, phrases?: readonly string[]): string;
+//# sourceMappingURL=thinking-phrases.d.ts.map

package/lib/types/types.d.ts

@@ -1,8 +1,27 @@
 import type { QaTurnSources } from "./provenance/types.js";
 export type QaSessionPolicy = "browser-persistent" | "new-on-load" | "fixed";
-export type QaSandboxMode = "read-only";
+export type QaSandboxMode = "read-only" | "workspace-write";
 export type QaApprovalPolicy = "never";
 export type QaToolPolicyMode = "allow-list";
+/**
+ * How a tool policy `ask` resolves on an attested QA agent. `blocked` refuses
+ * the call with the surface's own reason; `interactive` parks it until the
+ * operator answers in the QA view.
+ */
+export type QaApprovalInteraction = "blocked" | "interactive";
+/**
+ * How a user-questions request resolves on an attested QA agent. `unsupported`
+ * refuses the ask outright; `interactive` answers it from the QA view.
+ */
+export type QaQuestionInteraction = "unsupported" | "interactive";
+/** The operator's answer to one parked tool call. */
+export type QaApprovalDecision = "allowed-once" | "rejected";
+/** One answered question; `custom` is free text, and may accompany `selected`. */
+export interface QaQuestionAnswerItem {
+    readonly id: string;
+    readonly selected: readonly string[];
+    readonly custom?: string;
+}
 export type QaAccountRole = "user" | "admin";
 /** The account fields projected to browsers; never includes credentials. */
 export interface QaAccountUserPublic {
@@ -13,6 +32,36 @@ export interface QaAccountUserPublic {
     readonly createdAt: string;
     readonly lastLoginAt: string | null;
     readonly disabled: boolean;
+    /** Self-declared identity the QA prompt renders; empty until edited. */
+    readonly profile: QaAccountProfile;
+}
+/** One external system the deployment collects a handle for. */
+export interface QaAccountIdentityField {
+    /** Stable lowercase key: the profile's storage key and the prompt's label. */
+    readonly key: string;
+    /** Operator copy shown in the profile form. */
+    readonly label: string;
+}
+/**
+ * What one account says about itself. Every value is the owner's own wording,
+ * which is why the prompt renders it as self-declared rather than as a
+ * verified directory attribute.
+ */
+export interface QaAccountProfile {
+    /** Full name as the user writes it; empty when unset. */
+    readonly fullName: string;
+    /** External-system handles, keyed by the declared field key. */
+    readonly identities: Readonly<Record<string, string>>;
+    /** Free-form guidance about how the user wants answers; empty when unset. */
+    readonly instructions: string;
+    /** ISO timestamp of the last edit; null while the profile is untouched. */
+    readonly updatedAt: string | null;
+}
+/** Full-replace profile write: an absent value clears the stored one. */
+export interface QaAccountProfileInput {
+    readonly fullName: string;
+    readonly identities: Readonly<Record<string, string>>;
+    readonly instructions: string;
 }
 /** One successful login/registration: the bearer token plus the user. */
 export interface QaAccountSession {
@@ -77,6 +126,11 @@ export interface QaSourcesConfig {
         readonly inheritSources?: boolean;
         readonly enableReportToolFallback?: boolean;
         readonly markIncompleteOpaqueRuns?: boolean;
+        /**
+         * Whether a source the model writes into `qa_report_sources` must carry a
+         * usable path or URL. Off records the model's own type, title and snippet.
+         */
+        readonly validateReportedSources?: boolean;
     };
     readonly legacy?: {
         readonly parseAssistantSourcesBlock?: boolean;
@@ -117,13 +171,19 @@ export interface QaSurfaceConfig {
         readonly showToolActivity?: boolean;
         readonly showReasoning?: boolean;
         readonly renderMarkdown?: boolean;
-        readonly maxContentWidth?: number;
+        /** Floor for the visitor-resizable transcript/composer width; the page caps it. */
+        readonly minContentWidth?: number;
         readonly showSessionList?: boolean;
     };
     readonly suggestedQuestions?: readonly string[];
+    /**
+     * Phrases the running indicator cycles through. An empty list restores the
+     * built-in phrases: the indicator always carries a label.
+     */
+    readonly thinkingPhrases?: readonly string[];
     readonly interaction?: {
-        readonly approvals?: "blocked";
-        readonly questions?: "unsupported";
+        readonly approvals?: QaApprovalInteraction;
+        readonly questions?: QaQuestionInteraction;
     };
     readonly lockdown?: {
         readonly enabled?: boolean;
@@ -144,6 +204,8 @@ export interface QaSurfaceConfig {
             readonly mode?: QaToolPolicyMode;
             readonly allow?: readonly string[];
         };
+        /** Shared directories available to read-only filesystem tools. */
+        readonly sharedReadOnlyRoots?: readonly string[];
     };
     readonly embedding?: {
         readonly frameAncestors?: string | null;
@@ -155,6 +217,24 @@ export interface QaSurfaceConfig {
         readonly sessionTtlDays?: number;
         /** Let admins see chats owned by other QA accounts. */
         readonly showOtherUsersChats?: boolean;
+        /**
+         * Give every account a private cwd below the configured workspaceId.
+         * The child directory is not registered as a separate DSH workspace.
+         */
+        readonly perUserWorkspace?: boolean;
+        /** Self-declared profile: storage, the owner's form, and prompt injection. */
+        readonly profile?: {
+            readonly enabled?: boolean;
+            /** Render the profile into the QA agent's system prompt. */
+            readonly inject?: boolean;
+            /** External systems to collect a handle for; empty declares none. */
+            readonly identities?: readonly {
+                readonly key?: string;
+                readonly label?: string;
+            }[];
+            /** Character cap on the user's free-form agent guidance. */
+            readonly instructionsMaxLength?: number;
+        };
     };
     readonly entry?: {
         /** Inject the root → /qa redirect for non-loopback hostnames. */
@@ -163,6 +243,26 @@ export interface QaSurfaceConfig {
         readonly cookieBootstrap?: boolean;
     };
     readonly sources?: QaSourcesConfig;
+    readonly attachments?: QaAttachmentsConfig;
+}
+/** What a QA visitor may attach to one message. */
+export interface QaAttachmentsConfig {
+    /** Offer text files (md, txt, log, …) next to images; off = images only. */
+    readonly textFiles?: boolean;
+    /**
+     * Line count above which pasted plain text becomes an attached file instead
+     * of landing in the input field. Zero never converts.
+     */
+    readonly pastedTextLines?: number;
+    /** Byte ceiling for one attached file; the composer refuses anything larger. */
+    readonly maxFileBytes?: number;
+    /**
+     * Pending attachments (images plus text files) allowed on one message. The
+     * Host keeps its own authority over assembled image batches.
+     */
+    readonly maxPending?: number;
+    /** Accepted text-file extensions, lowercase and without the dot. */
+    readonly extensions?: readonly string[];
 }
 export interface ResolvedQaSurfaceConfig {
     readonly enabled: boolean;
@@ -197,13 +297,14 @@ export interface ResolvedQaSurfaceConfig {
         readonly showToolActivity: boolean;
         readonly showReasoning: boolean;
         readonly renderMarkdown: boolean;
-        readonly maxContentWidth: number;
+        readonly minContentWidth: number;
         readonly showSessionList: boolean;
     };
     readonly suggestedQuestions: readonly string[];
+    readonly thinkingPhrases: readonly string[];
     readonly interaction: {
-        readonly approvals: "blocked";
-        readonly questions: "unsupported";
+        readonly approvals: QaApprovalInteraction;
+        readonly questions: QaQuestionInteraction;
     };
     readonly lockdown: {
         readonly enabled: boolean;
@@ -224,6 +325,7 @@ export interface ResolvedQaSurfaceConfig {
             readonly mode: QaToolPolicyMode;
             readonly allow: readonly string[];
         };
+        readonly sharedReadOnlyRoots: readonly string[];
     };
     readonly embedding: {
         readonly frameAncestors: string | null;
@@ -233,6 +335,13 @@ export interface ResolvedQaSurfaceConfig {
         readonly allowRegistration: boolean;
         readonly sessionTtlDays: number;
         readonly showOtherUsersChats: boolean;
+        readonly perUserWorkspace: boolean;
+        readonly profile: {
+            readonly enabled: boolean;
+            readonly inject: boolean;
+            readonly identities: readonly QaAccountIdentityField[];
+            readonly instructionsMaxLength: number;
+        };
     };
     readonly entry: {
         readonly redirectNonLoopback: boolean;
@@ -273,11 +382,19 @@ export interface ResolvedQaSurfaceConfig {
             readonly inheritSources: boolean;
             readonly enableReportToolFallback: boolean;
             readonly markIncompleteOpaqueRuns: boolean;
+            readonly validateReportedSources: boolean;
         };
         readonly legacy: {
             readonly parseAssistantSourcesBlock: boolean;
         };
     };
+    readonly attachments: {
+        readonly textFiles: boolean;
+        readonly pastedTextLines: number;
+        readonly maxFileBytes: number;
+        readonly maxPending: number;
+        readonly extensions: readonly string[];
+    };
 }
 export interface QaSourceFilePreview {
     readonly path: string;
@@ -294,7 +411,7 @@ export interface QaLockdownProof {
     readonly agentPresetMatches: boolean;
     readonly workspaceMatches: boolean;
     readonly modelMatches: boolean;
-    readonly sandboxIsReadOnly: boolean;
+    readonly sandboxModeMatches: boolean;
     readonly approvalIsNever: boolean;
     readonly permissionPreset: string;
     readonly toolPolicyLoaded: boolean;
@@ -307,6 +424,8 @@ export type QaMessage = {
     readonly status: "committed";
     readonly timestamp?: number;
     readonly images?: readonly QaImageView[];
+    /** Durable files the user attached to this message, in prompt order. */
+    readonly files?: readonly QaFileView[];
     /**
      * Chat owner's display name, set only for an admin reading a foreign
      * chat; the owner themself sees their messages unlabeled.
@@ -348,7 +467,8 @@ export type QaMessage = {
     readonly id: string;
     readonly role: "work";
     readonly turn: number;
-    readonly status: "running" | "complete";
+    /** "error" marks a turn the host ended with a provider failure. */
+    readonly status: "running" | "complete" | "error";
     readonly startedAt?: number;
     readonly endedAt?: number;
     readonly items: readonly QaWorkItem[];
@@ -380,6 +500,7 @@ export type QaSource = import("./provenance/types.js").QaSourceReference;
 export type QaImageMediaType = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
 /** One image pending in the composer, browser-owned until the prompt lands. */
 export interface QaImageDraft {
+    readonly kind: "image";
     readonly id: string;
     readonly mediaType: QaImageMediaType;
     readonly name: string;
@@ -388,16 +509,85 @@ export interface QaImageDraft {
     /** Local object URL for the preview thumbnail. */
     readonly previewUrl: string;
 }
+/**
+ * One file pending in the composer. The bytes stay in the browser until the
+ * prompt is sent: an image can ride the prompt inline, but a file must be
+ * staged through the Host upload route first and then cited by its receipt.
+ */
+export interface QaFileDraft {
+    readonly kind: "file";
+    readonly id: string;
+    readonly name: string;
+    readonly bytes: number;
+    /** Verbatim payload; a pasted blob is a File built from the pasted text. */
+    readonly blob: Blob;
+}
+/** Anything the composer may hold before the prompt is sent. */
+export type QaAttachmentDraft = QaImageDraft | QaFileDraft;
 /** A durable image attached to a sent message. */
 export interface QaImageView {
     readonly attachmentId: string;
     readonly mediaType: QaImageMediaType;
 }
+/**
+ * A durable file attached to a sent message. The browser never reads these
+ * bytes back (the attachment route serves images); the row shows the handle
+ * the model resolves, and the Host keeps the verbatim copy.
+ */
+export interface QaFileView {
+    readonly attachmentId: string;
+    readonly name: string;
+    readonly bytes: number;
+}
 /** A subagent transcript opened read-only from the agents panel. */
 export interface QaSubagentView {
     readonly id: string;
     readonly title: string;
 }
+/**
+ * One tool call waiting for the operator. The browser lists these over its own
+ * remote and answers them one by one; nothing here is answered automatically.
+ */
+export interface QaPendingApproval {
+    readonly id: string;
+    /** The chat the request belongs to: a delegated child asks under its root. */
+    readonly sessionId: string;
+    readonly toolName: string;
+    /** The reason the composed gate gave for asking, when it gave one. */
+    readonly reason: string | null;
+    readonly createdAt: number;
+    /** True when a delegated child of the chat made the call. */
+    readonly delegated: boolean;
+}
+/**
+ * One question waiting for the operator, normalized for the form the QA view
+ * renders. The protocol fields are the harness user-questions contract; absent
+ * ones become explicit nulls so the browser never branches on undefined.
+ */
+export interface QaPendingQuestionItem {
+    readonly id: string;
+    readonly question: string;
+    readonly header: string | null;
+    readonly detail: string | null;
+    readonly options: readonly QaPendingQuestionOption[];
+    readonly multiSelect: boolean;
+}
+export interface QaPendingQuestionOption {
+    readonly label: string;
+    readonly description: string | null;
+}
+/**
+ * One user-questions request parked for the operator. A single request carries
+ * every question the model asked in one call, so the card is a form with a
+ * pager, not a list of independent prompts.
+ */
+export interface QaPendingQuestion {
+    readonly id: string;
+    /** The chat the request belongs to. */
+    readonly sessionId: string;
+    readonly questions: readonly QaPendingQuestionItem[];
+    readonly createdAt: number;
+}
 export interface QaSessionState {
     readonly phase: QaSessionPhase;
     readonly sessionId: string | null;
@@ -413,5 +603,9 @@ export interface QaSessionState {
     readonly incompleteSourceOrigins: QaTurnSources["incompleteOrigins"];
     /** Set while the bound session is a subagent watched from the panel. */
     readonly viewingSubagent: QaSubagentView | null;
+    /** Tool calls parked for the operator's answer, oldest first. */
+    readonly approvals: readonly QaPendingApproval[];
+    /** Question requests parked for the operator's answer, oldest first. */
+    readonly questions: readonly QaPendingQuestion[];
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types/user-workspace.d.ts

@@ -0,0 +1,42 @@
+/** Stable, non-workspace child used to keep account directories out of sight. */
+export declare const QA_USER_WORKSPACES_DIRECTORY = ".qa-users";
+/** Conservative fixed budgets; there is deliberately no browser override. */
+export declare const QA_USER_WORKSPACE_MAX_BYTES: number;
+export declare const QA_USER_WORKSPACE_MAX_WRITE_BYTES: number;
+export interface QaToolExecutionLike {
+    readonly name: string;
+    readonly arguments: unknown;
+}
+export interface QaUserWorkspaceReadPolicy {
+    /** Shared directories exposed only to read-only filesystem tools. */
+    readonly sharedReadOnlyRoots?: readonly string[];
+}
+export declare function pathIsInside(target: string, root: string): boolean;
+/**
+ * Resolve the deepest existing ancestor, preserving the missing suffix. This
+ * catches symlink escapes for reads and for files which a write is about to
+ * create.
+ */
+export declare function canonicalCandidate(input: string): string;
+/**
+ * Materialize `<registered workspace>/.qa-users/<account UUID>` without
+ * registering the child as a DSH Workspace. Both directory levels reject
+ * symlinks, and their real paths must stay below the configured workspace.
+ */
+export declare function prepareQaUserWorkspace(workspaceRoot: string, userId: string): string;
+/** Resolve an already provisioned account directory for admission checks. */
+export declare function existingQaUserWorkspace(workspaceRoot: string, userId: string): string;
+/**
+ * Monotonic guard used in addition to DSH's workspace-write sandbox. It
+ * fences model-controlled file paths for both reads and writes, rejects tools
+ * whose implementation can walk above cwd, and enforces bounded scratch use.
+ *
+ * `attachmentRoot` is the one deliberate read exemption: an uploaded file is
+ * an immutable content-addressed copy the deployment stores outside every
+ * workspace, and the model reaches it exactly as the harness intends (the
+ * prompt carries the stored path). Reads of a single such file are allowed;
+ * directory-wide tools stay confined because the store is shared by every
+ * account, and writes are never exempted.
+ */
+export declare function qaUserWorkspaceDenial(execution: QaToolExecutionLike, root: string, attachmentRoot?: string, readPolicy?: QaUserWorkspaceReadPolicy): string | undefined;
+//# sourceMappingURL=user-workspace.d.ts.map