@yadsh/dsh-qa-surface 0.9.0 → 0.10.0

package/lib/types/provenance/document-preview.d.ts

@@ -0,0 +1,24 @@
+import type { DocumentsFace } from "@yadsh/dsh-documents";
+import type { QaDocumentPreview } from "../types.js";
+import { type QaAllowedFileRequest } from "./file-preview.js";
+/** Look up the document subsystem a sibling Host plugin published. */
+export type DocumentsLookup = () => DocumentsFace | undefined;
+export interface QaDocumentPreviewRequest extends QaAllowedFileRequest {
+    /** The document pipeline, resolved per call so a late provider still counts. */
+    readonly documents: DocumentsLookup;
+    readonly sessionId: string;
+    /** Bytes of the rendered PDF the panel accepts before it gives up. */
+    readonly maxBytes: number;
+}
+/**
+ * Render one Word document as a PDF for the files panel.
+ *
+ * The conversion is the document pipeline's own — the same runtime, providers
+ * and limits the `document_*` tools use — reached through the face that plugin
+ * publishes for its Host siblings; a deployment without the pipeline installed
+ * refuses with `unsupported` rather than growing a second converter here. The
+ * input path passes the same containment check the panel's other reads use, so
+ * a preview cannot read what a listing could not reach.
+ */
+export declare function previewConvertibleDocument({ documents, sessionId, maxBytes, ...file }: QaDocumentPreviewRequest): Promise<QaDocumentPreview>;
+//# sourceMappingURL=document-preview.d.ts.map

package/lib/types/provenance/file-preview.d.ts

@@ -1,11 +1,13 @@
-import type { QaSourceFilePreview } from "../types.js";
+import type { QaSourceFilePreview, QaWorkspaceFile, QaWorkspaceListing } from "../types.js";
 /**
  * Coarse, wire-safe preview refusal codes. They ride the shared
  * `(reason: <code>)` marker, so the panel can tell "this file is not in a
  * directory the QA read policy opens" from "this file is gone" instead of
  * telling every audience that a present file moved away.
  */
-export type QaSourcePreviewReason = "outside-roots" | "not-evidence" | "unavailable";
+export type QaSourcePreviewReason = "outside-roots" | "not-evidence" | "unavailable"
+/** The panel has no way to render this format at all. */
+ | "unsupported";
 /** Host refusal whose wire message carries the coarse reason marker. */
 export declare class QaSourcePreviewError extends Error {
     readonly reason: QaSourcePreviewReason;
@@ -39,6 +41,32 @@ export interface QaSourceFilePreviewRequest {
     readonly maxBytes: number;
     readonly maxMarkdownRenderBytes: number;
 }
+/** A file request the panel may make: the chat's own tree or a shared root. */
+export interface QaAllowedFileRequest {
+    readonly filePath: string;
+    /** The attested chat's cwd: the anchor a relative request resolves against. */
+    readonly cwd: string;
+    readonly sharedReadOnlyRoots?: readonly string[];
+    readonly attachmentRoot?: string;
+}
+/** One resolved file that passed the read policy. */
+interface QaAllowedFile {
+    /** The path as the caller spelled it, canonicalized against the chat cwd. */
+    readonly canonicalPath: string;
+    /** Its real filesystem path, once symlinks are followed. */
+    readonly canonical: string;
+    readonly size: number;
+}
+/**
+ * Resolve one requested file and check it against the readable roots.
+ *
+ * The roots mirror the per-user execution guard — the chat's own cwd plus the
+ * deployment's shared read-only directories and the attachment store — so a
+ * file the model was explicitly allowed to read stays readable in the panel,
+ * while anything else is refused with the coarse `outside-roots` reason
+ * instead of leaking whether it exists.
+ */
+export declare function resolveAllowedFile({ filePath, cwd, sharedReadOnlyRoots, attachmentRoot, }: QaAllowedFileRequest): Promise<QaAllowedFile>;
 /**
  * Read one evidence file from the roots the QA read policy opens.
  *
@@ -50,4 +78,43 @@ export interface QaSourceFilePreviewRequest {
  * refused as foreign evidence.
  */
 export declare function readSourceFilePreview({ sourcePath, cwd, isEvidence, sharedReadOnlyRoots, attachmentRoot, maxBytes, maxMarkdownRenderBytes, }: QaSourceFilePreviewRequest): Promise<QaSourceFilePreview>;
+/** One directory request from the files panel. */
+export interface QaWorkspaceListRequest {
+    /** The directory to list, absolute or relative to the chat cwd. Empty = root. */
+    readonly dirPath: string;
+    readonly cwd: string;
+    /** Children one listing carries; the rest is reported as truncated. */
+    readonly maxEntries: number;
+}
+/** The advertised type of one file: by extension, else opaque bytes. */
+export declare function mediaTypeOf(path: string): string;
+/**
+ * List one directory of the chat's own workspace.
+ *
+ * Browsing is deliberately narrower than previewing: the panel walks the tree
+ * the chat works in, never the deployment's shared read-only roots, so the
+ * visitor cannot enumerate the deployment from the rail. The request is
+ * confined with the same realpath-then-contain check the preview uses, which
+ * is what makes `..` and symlinked directories harmless.
+ * Symlinked children are omitted rather than followed: a link inside the
+ * workspace may point anywhere, and a tree that silently leaves the chat's
+ * directory is worse than one that hides a link.
+ */
+export declare function listWorkspaceDirectory({ dirPath, cwd, maxEntries, }: QaWorkspaceListRequest): Promise<QaWorkspaceListing>;
+/** One file request from the files panel. */
+export interface QaWorkspaceFileRequest extends QaAllowedFileRequest {
+    readonly maxBytes: number;
+    readonly maxMarkdownRenderBytes: number;
+}
+/**
+ * Read one file of the chat's workspace for the panel: text when it decodes as
+ * UTF-8, base64 bytes when it does not, so a document the agent produced can be
+ * offered for download while a note previews inline.
+ *
+ * Unlike the source preview this is not bound to recorded evidence — the panel
+ * browses what the chat's workspace holds — but it is bound to the same roots
+ * the model itself may read.
+ */
+export declare function readWorkspaceFile({ filePath, cwd, sharedReadOnlyRoots, attachmentRoot, maxBytes, maxMarkdownRenderBytes, }: QaWorkspaceFileRequest): Promise<QaWorkspaceFile>;
+export {};
 //# sourceMappingURL=file-preview.d.ts.map

package/lib/types/qa-tools/catalog.d.ts

@@ -8,7 +8,7 @@ import type { QaToolDescriptor } from "./types.js";
  *
  * Bump it whenever the catalog's tool set or their schemas change.
  */
-export declare const QA_TOOL_CATALOG_VERSION = "1";
+export declare const QA_TOOL_CATALOG_VERSION = "2";
 /** One QA tool reports the activation state of whichever agent calls it. */
 export interface QaToolsSelfcheckDeps {
     readonly catalogVersion: string;

package/lib/types/qa-tools/file-delete-gate.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { QaSessionOwnership } from "../session-ownership.js";
+/** The one QA tool whose every call is parked for the operator. */
+export declare const QA_FILE_DELETE_TOOL = "file_delete";
+/** Why the gate answers `ask` before the chain can decide alone. */
+export declare const QA_FILE_DELETE_ASK_REASON = "deleting a workspace file requires operator confirmation";
+/**
+ * The inner half of `file_delete`'s safety: the decision that composes the
+ * approval flow around one destructive tool.
+ *
+ * Installed WITHOUT `prepend`, deliberately. The approval gate sits outside
+ * every other `tools/pre-execute` listener and resolves the decision the rest
+ * of the chain produced — an `ask` from an inner gate is what it parks for
+ * the operator. This listener is that inner gate: for a `file_delete` call
+ * from an attested QA session it answers `ask` on its own, without asking
+ * the chain, so the interactive approval card appears for every deletion,
+ * whatever the deployment's other policies would have said. The operator's
+ * answer becomes the decision, and on a deployment with
+ * `interaction.approvals: blocked` the approval gate keeps its fail-closed
+ * behavior and refuses the call — nothing is ever deleted without a person.
+ *
+ * Any other tool, and any caller this deployment did not attest, is handed
+ * back to the chain untouched.
+ */
+export declare class QaFileDeleteGate {
+    private readonly ctx;
+    private readonly ownership;
+    private readonly disposers;
+    constructor(ctx: Context, ownership: QaSessionOwnership);
+    /** Sit inside the approval gate; registration order is the composition. */
+    install(): void;
+    /** Detach the listener. Wired as an effect, like every other gate. */
+    dispose(): void;
+    private handle;
+    /**
+     * Whether this deployment attested the chat the call belongs to, delegated
+     * children included. The same ownership service the approval gate reads,
+     * so one chat is parked under exactly one surface.
+     */
+    private attested;
+}
+//# sourceMappingURL=file-delete-gate.d.ts.map

package/lib/types/qa-tools/file-delete.d.ts

@@ -0,0 +1,32 @@
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/**
+ * `file_delete` — the QA catalog's one destructive capability.
+ *
+ * The QA surface serves untrusted-audience chats pinned to a read-only or
+ * workspace-write sandbox, and until now no chat could remove a file it had
+ * created. This tool deletes exactly one regular file strictly inside the
+ * calling agent's workspace root (the session cwd) and refuses everything
+ * else with a reason the model can act on: directories, missing paths, paths
+ * spelled outside the root, and paths that leave it through a symbolic link.
+ * Every call is additionally answered `ask` by the always-ask gate, so the
+ * interactive approval card parks it for the operator before this body ever
+ * runs — the fence here is the second of two boundaries, not the only one.
+ *
+ * The workspace root is read from `exec.agent` at call time, so building the
+ * tool (and the catalog that carries it) stays side-effect free.
+ */
+/** Why `file_delete` refused a call. */
+export type QaFileDeleteRefusal = "workspace-unavailable" | "outside-workspace" | "symlink-escape" | "not-found" | "not-a-file";
+/**
+ * A typed refusal of one `file_delete` call.
+ *
+ * The message is what the model reads; it names the reason in words and
+ * deliberately never echoes the requested absolute host path, so a refusal
+ * cannot leak the deployment's layout into the conversation.
+ */
+export declare class QaFileDeleteError extends Error {
+    readonly code: QaFileDeleteRefusal;
+    constructor(code: QaFileDeleteRefusal, message: string, options?: ErrorOptions);
+}
+export declare function createFileDeleteTool(): ToolDefinition;
+//# sourceMappingURL=file-delete.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * Formats the files panel previews by conversion instead of by bytes.
+ *
+ * Shared by the Host half (which owns the conversion) and the browser card
+ * (which decides whether opening a file should ask for one), so the two cannot
+ * drift on what "we can render this" means. Dependency-free on purpose: the
+ * card bundle inlines it.
+ */
+/** OOXML word-processing documents, as the deployment detects them. */
+export declare const QA_WORD_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+/** The media type of the PDF a converted document arrives as. */
+export declare const QA_PDF_MEDIA_TYPE = "application/pdf";
+/**
+ * Whether the panel asks the Host for a converted PDF rather than rendering the
+ * bytes it already holds. Word documents are the whole set: the document
+ * pipeline reads them and renders PDF, while its other inputs are already
+ * previewable (Markdown as text, PDF through the browser's own viewer).
+ */
+export declare function isConvertibleDocument(mediaType: string): boolean;
+//# sourceMappingURL=documents.d.ts.map

package/lib/types/types.d.ts

@@ -489,6 +489,7 @@ export interface QaSourcesConfig {
         readonly allowRawToggle?: boolean;
         readonly maxBytes?: number;
         readonly maxMarkdownRenderBytes?: number;
+        readonly maxListingEntries?: number;
     };
     readonly subagents?: {
         readonly inheritSources?: boolean;
@@ -504,6 +505,30 @@ export interface QaSourcesConfig {
         readonly parseAssistantSourcesBlock?: boolean;
     };
 }
+/**
+ * The ambient notes the injector writes into a QA chat as plugin-sourced user
+ * messages (`prompt-notes.ts`). Each note can be switched off and reworded;
+ * an empty template keeps the built-in wording.
+ */
+export interface QaNotesConfig {
+    /** Who the assistant is talking to; `{identity}` + `{instructions}`. */
+    readonly identity?: {
+        readonly enabled?: boolean;
+        readonly template?: string;
+    };
+    /** Source-provenance rules; `{reportTool}` names the subagent report tool. */
+    readonly sources?: {
+        readonly enabled?: boolean;
+        readonly template?: string;
+        /** The sentence appended when the report-tool fallback is on. */
+        readonly fallbackTemplate?: string;
+    };
+    /** How to label background delegations; no placeholders. */
+    readonly delegation?: {
+        readonly enabled?: boolean;
+        readonly template?: string;
+    };
+}
 export interface QaSurfaceConfig {
     readonly enabled?: boolean;
     readonly route?: {
@@ -684,6 +709,7 @@ export interface QaSurfaceConfig {
     };
     readonly sources?: QaSourcesConfig;
     readonly attachments?: QaAttachmentsConfig;
+    readonly notes?: QaNotesConfig;
 }
 /** What a QA visitor may attach to one message. */
 export interface QaAttachmentsConfig {
@@ -854,6 +880,7 @@ export interface ResolvedQaSurfaceConfig {
             readonly allowRawToggle: boolean;
             readonly maxBytes: number;
             readonly maxMarkdownRenderBytes: number;
+            readonly maxListingEntries: number;
         };
         readonly subagents: {
             readonly inheritSources: boolean;
@@ -872,6 +899,21 @@ export interface ResolvedQaSurfaceConfig {
         readonly maxPending: number;
         readonly extensions: readonly string[];
     };
+    readonly notes: {
+        readonly identity: {
+            readonly enabled: boolean;
+            readonly template: string;
+        };
+        readonly sources: {
+            readonly enabled: boolean;
+            readonly template: string;
+            readonly fallbackTemplate: string;
+        };
+        readonly delegation: {
+            readonly enabled: boolean;
+            readonly template: string;
+        };
+    };
 }
 /** Which native registry one unified entry came from. */
 export type QaSlashEntryKind = "skill" | "command";
@@ -1038,6 +1080,51 @@ export interface QaSourceFilePreview {
     readonly markdown: boolean;
     readonly renderableMarkdown: boolean;
 }
+/**
+ * A file the panel renders by conversion rather than by bytes: the document
+ * pipeline turned a Word file into PDF, and the browser shows that PDF.
+ */
+export interface QaDocumentPreview {
+    readonly kind: "pdf";
+    readonly base64: string;
+    readonly mime: "application/pdf";
+    readonly name: string;
+    readonly bytes: number;
+}
+/** One directory entry of a chat's own workspace, as the files panel browses it. */
+export interface QaWorkspaceEntry {
+    readonly name: string;
+    readonly type: "file" | "directory";
+    readonly size: number | null;
+}
+/**
+ * One directory of the chat's workspace. `path` is the canonical form of the
+ * directory as requested — the chat root itself is the empty string — so the
+ * panel can build a breadcrumb without another round trip.
+ */
+export interface QaWorkspaceListing {
+    readonly path: string;
+    readonly entries: readonly QaWorkspaceEntry[];
+    /** More children existed than one listing carries. */
+    readonly truncated: boolean;
+}
+/**
+ * One file of the chat's workspace: decoded text when it reads as UTF-8, base64
+ * bytes when it does not. The panel needs both — documents the agent produced
+ * are binary, while notes and transcripts preview as text.
+ */
+export interface QaWorkspaceFile {
+    readonly path: string;
+    readonly size: number;
+    readonly truncated: boolean;
+    readonly markdown: boolean;
+    readonly renderableMarkdown: boolean;
+    readonly mime: string;
+    /** Present when the file decoded as text; absent for binary content. */
+    readonly text?: string;
+    /** Present when the file is not text; base64 of at most the byte cap. */
+    readonly base64?: string;
+}
 /** Host-attested facts required before the QA composer may become writable. */
 export interface QaLockdownProof {
     readonly sessionId: string;
@@ -1614,7 +1701,12 @@ export interface QaAdminUserDetail {
     }[];
     readonly activity: {
         readonly conversations: number;
-        readonly messages: number;
+        /**
+         * Unknown until the conversations page is opened: the count needs every
+         * conversation's log read, so the detail card reports null instead of
+         * blocking its payload on the scan.
+         */
+        readonly messages: number | null;
         readonly positiveRatings: number;
         readonly negativeRatings: number;
     };

package/lib/types/ui-mode.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The deployment UI mode, as the host half of the plugin sees it.
+ *
+ * `DSH_UI_MODE=qa` (the kiosk) moves the frontend URL-space ownership from
+ * this plugin to the harness: the harness route policy serves `/qa` directly,
+ * redirects `/` into it, and answers every other frontend path with 404. The
+ * plugin's own navigation redirect route must then stay unregistered — it
+ * exists for the overlay composition, where the index is served at `/` and a
+ * browser navigation to `/qa` has to bounce through the marker hand-off —
+ * because a registered route shadows the harness fallback seat and would
+ * loop every `/qa` navigation back onto itself.
+ */
+/**
+ * Whether this harness process runs the QA kiosk UI mode.
+ * @param env - the process environment; overridable for tests.
+ */
+export declare function qaKioskDeployment(env?: Readonly<Record<string, string | undefined>>): boolean;
+//# sourceMappingURL=ui-mode.d.ts.map

package/lib/ui-mode.js

@@ -0,0 +1,22 @@
+/**
+ * The deployment UI mode, as the host half of the plugin sees it.
+ *
+ * `DSH_UI_MODE=qa` (the kiosk) moves the frontend URL-space ownership from
+ * this plugin to the harness: the harness route policy serves `/qa` directly,
+ * redirects `/` into it, and answers every other frontend path with 404. The
+ * plugin's own navigation redirect route must then stay unregistered — it
+ * exists for the overlay composition, where the index is served at `/` and a
+ * browser navigation to `/qa` has to bounce through the marker hand-off —
+ * because a registered route shadows the harness fallback seat and would
+ * loop every `/qa` navigation back onto itself.
+ */
+/** Environment variable selecting the deployment UI mode (`qa` = kiosk). */
+const UI_MODE_ENV = "DSH_UI_MODE";
+/**
+ * Whether this harness process runs the QA kiosk UI mode.
+ * @param env - the process environment; overridable for tests.
+ */
+export function qaKioskDeployment(env = process.env) {
+    return (env[UI_MODE_ENV] ?? "").trim() === "qa";
+}
+//# sourceMappingURL=ui-mode.js.map

package/lib/ui-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-mode.js","sourceRoot":"","sources":["../src/ui-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,GAAG,aAAa,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAG,GAAiD,OAAO,CAAC,GAAG;IAE/D,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC;AAClD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadsh/dsh-qa-surface",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
   "repository": {
     "type": "git",
@@ -102,15 +102,14 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-api-gateway": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-agent": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-agent-presets": ">=0.1.5-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-api-gateway": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-api-session-controller": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-api-workspace-controller": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-client-connection": ">=0.1.5-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-client-ui-chat": ">=0.1.5-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-client-ui-layout": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-client-ui-renderer": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-client-ui-settings": ">=0.1.5-rc.2 <0.2.0",
@@ -127,28 +126,29 @@
     "@deepseek-ai/dsh-tools": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-workspace": ">=0.1.5-rc.2 <0.2.0",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "dependencies": {
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@yadsh/dsh-audit-ui": "^0.1.0",
     "@yadsh/dsh-audit-core": "^0.1.0",
+    "@yadsh/dsh-audit-ui": "^0.1.0",
+    "@yadsh/dsh-documents": "^0.4.0",
     "@yadsh/dsh-plugin-kit": "^0.3.0",
     "@yadsh/dsh-plugin-log": "^0.4.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/schemastery": "3.18.2",
-    "@deepseek-ai/dsh-api-gateway": "0.1.5-rc.2",
     "@deepseek-ai/dsh-agent": "0.1.5-rc.2",
     "@deepseek-ai/dsh-agent-presets": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-api-gateway": "0.1.5-rc.2",
     "@deepseek-ai/dsh-api-session-controller": "0.1.5-rc.2",
     "@deepseek-ai/dsh-api-workspace-controller": "0.1.5-rc.2",
     "@deepseek-ai/dsh-client-connection": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.5-rc.2",
     "@deepseek-ai/dsh-client-ui-chat": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.5-rc.2",
     "@deepseek-ai/dsh-client-ui-layout": "0.1.5-rc.2",
     "@deepseek-ai/dsh-client-ui-renderer": "0.1.5-rc.2",
     "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2",
@@ -167,12 +167,14 @@
     "@deepseek-ai/dsh-typert-generator": "0.1.5-rc.2",
     "@deepseek-ai/dsh-typert-protocol": "0.1.5-rc.2",
     "@deepseek-ai/dsh-workspace": "0.1.5-rc.2",
+    "@deepseek-ai/schemastery": "3.18.2",
     "@testing-library/react": "^16.3.0",
     "@types/node": "^26.4.0",
     "@types/react": "18.3.28",
     "@types/react-dom": "18.3.7",
     "eslint": "10.9.1",
     "jsdom": "^26.1.0",
+    "katex": "^0.16.47",
     "playwright": "1.62.1",
     "react": "18.3.1",
     "react-dom": "18.3.1",