@yadsh/dsh-qa-surface 0.9.0 → 0.11.0

package/lib/types/types.d.ts

@@ -42,7 +42,9 @@ export interface QaQuestionAnswerItem {
  */
 export type QaAccountRole = "user" | "reviewer" | "admin";
 /** Administrative permissions a role grants; see `admin/permissions.ts`. */
-export type QaPermission = "users.read" | "users.manage" | "roles.read" | "roles.manage" | "conversations.read.all" | "conversations.read.own" | "conversations.delete" | "reviews.read" | "reviews.write" | "analytics.read" | "audit.read" | "settings.manage";
+export type QaPermission = "users.read" | "users.manage" | "roles.read" | "roles.manage" | "conversations.read.all" | "conversations.read.own" | "conversations.delete" | "reviews.read" | "reviews.write" | "analytics.read" | "audit.read" | "settings.manage"
+/** Write access to skill files, personal and deployment-wide. */
+ | "skills.manage";
 /**
  * Tools split by how they become available. `always` is visible from the first
  * model step; `skillGrantable` is a ceiling — the tool only appears once an
@@ -342,6 +344,21 @@ export interface QaAccountSession {
     readonly token: string;
     readonly user: QaAccountUserPublic;
 }
+/**
+ * One forgotten-password request waiting for an operator. The address and name
+ * travel with it so the console can show who is locked out without a second
+ * lookup; the count makes repeated taps visible instead of silent.
+ */
+export interface QaPasswordResetRequest {
+    readonly userId: string;
+    readonly email: string;
+    readonly displayName: string;
+    readonly requestedAt: string;
+    readonly lastRequestedAt: string;
+    readonly requestCount: number;
+    /** True when the account is disabled: a reset will not let it sign in. */
+    readonly disabled: boolean;
+}
 export type QaWhoamiResult = {
     readonly authenticated: false;
 } | {
@@ -354,6 +371,45 @@ export interface QaClaimResult {
     /** Ids already owned by a different user; the browser drops them. */
     readonly conflicts: readonly string[];
 }
+/**
+ * What an integration token may do. The credential a non-browser application
+ * presents to the QA HTTP API carries its own scopes, so a bridge that asks
+ * questions cannot read back conversations it was never given.
+ */
+export type QaServiceTokenScope = "ask" | "sessions:read";
+/**
+ * What an account asks a new integration token to be. The credential is always
+ * issued to the caller: nothing a browser sends may name another account, so
+ * this shape has no owner field and the administrative path keeps its own.
+ */
+export interface QaServiceTokenCreateInput {
+    /** A note the operator's list shows; empty becomes a generic label. */
+    readonly label?: string;
+    /** Requested scopes; unknown ones are dropped, empty falls back to `ask`. */
+    readonly scopes?: readonly string[];
+    /** How long the token lives, in days; bounded server-side. */
+    readonly ttlDays?: number;
+}
+/**
+ * One integration token as a list shows it. The plaintext is deliberately not
+ * part of this shape: a secret is shown once, when it is minted, and a list
+ * that could repeat it would be a list that leaks it.
+ */
+export interface QaServiceTokenSummary {
+    readonly id: string;
+    readonly label: string;
+    readonly scopes: readonly QaServiceTokenScope[];
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly lastUsedAt: string | null;
+    readonly revokedAt: string | null;
+    readonly useCount: number;
+}
+/** One freshly minted token: the plaintext is here and nowhere else, ever. */
+export interface QaIssuedServiceToken extends QaServiceTokenSummary {
+    /** The credential to hand to the integration. Never recoverable later. */
+    readonly token: string;
+}
 /**
  * One chat-ownership entry as the admin views see it: the session, its owner
  * and the owner's display name resolved at read time (a disabled account
@@ -388,6 +444,44 @@ export type QaSkillJsonValue = string | number | boolean | null | readonly QaSki
     readonly [key: string]: QaSkillJsonValue;
 };
 /** One personal skill as the catalog list renders it. */
+/**
+ * One administrator write to a skill somebody else owns.
+ *
+ * The record exists so a personal skill cannot be changed behind its owner's
+ * back: it is written beside the skill and reported on every read, and the
+ * owner sees the badge in their own catalog.
+ */
+export interface QaSkillAdminEdit {
+    /** Administrator account id; the owner is told a role, not a colleague. */
+    readonly actorId: string;
+    /** ISO timestamp of that write. */
+    readonly at: string;
+}
+/**
+ * Which skill store an administrator is editing: the deployment-wide shared
+ * root every account may read, or one account's own directory.
+ */
+export type QaAdminSkillScope = {
+    readonly kind: "shared";
+} | {
+    readonly kind: "user";
+    readonly userId: string;
+};
+/** The account a personal skill scope belongs to, for the console's header. */
+export interface QaAdminSkillOwner {
+    readonly userId: string;
+    readonly email: string;
+    readonly displayName: string;
+}
+/** One scope's catalog plus the facts the console names it by. */
+export interface QaAdminSkillsView {
+    readonly scope: QaAdminSkillScope;
+    /** The account of a personal scope; null for the shared root. */
+    readonly owner: QaAdminSkillOwner | null;
+    readonly skills: readonly QaSkillSummary[];
+    /** Absolute directory this scope reads and writes, rendered read-only. */
+    readonly rootPath: string;
+}
 export interface QaSkillSummary {
     readonly name: string;
     readonly description: string;
@@ -405,6 +499,13 @@ export interface QaSkillSummary {
     readonly updatedAt: string | null;
     /** sha256 of the stored bytes; an update must echo the revision it read. */
     readonly revision: string;
+    /**
+     * The administrator write that produced the stored revision, or null. A
+     * record whose revision no longer matches is stale and reports as null: the
+     * badge answers "did an administrator write what I am looking at", not
+     * "was this skill ever touched by an administrator".
+     */
+    readonly adminEdit: QaSkillAdminEdit | null;
 }
 /** One personal skill with everything the editor needs. */
 export interface QaSkillDocument extends QaSkillSummary {
@@ -489,6 +590,7 @@ export interface QaSourcesConfig {
         readonly allowRawToggle?: boolean;
         readonly maxBytes?: number;
         readonly maxMarkdownRenderBytes?: number;
+        readonly maxListingEntries?: number;
     };
     readonly subagents?: {
         readonly inheritSources?: boolean;
@@ -504,6 +606,40 @@ 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;
+    };
+    /** Which reader an attached office document belongs to; no placeholders. */
+    readonly documents?: {
+        readonly enabled?: boolean;
+        readonly template?: string;
+    };
+    /** Where an answer should come from; no placeholders. */
+    readonly sourcePriority?: {
+        readonly enabled?: boolean;
+        readonly template?: string;
+    };
+}
 export interface QaSurfaceConfig {
     readonly enabled?: boolean;
     readonly route?: {
@@ -684,6 +820,43 @@ export interface QaSurfaceConfig {
     };
     readonly sources?: QaSourcesConfig;
     readonly attachments?: QaAttachmentsConfig;
+    readonly notes?: QaNotesConfig;
+    readonly integration?: QaIntegrationConfig;
+}
+/**
+ * The HTTP API an external application (the ticket bridge) uses to ask
+ * questions and read its own conversations back: `POST {basePath}/ask`,
+ * `GET {basePath}/session` and `GET {basePath}/health`, authenticated with an
+ * account's integration token. Off unless a deployment asks for it.
+ */
+export interface QaIntegrationConfig {
+    /** Serve the API at all. Requires accounts; off by default. */
+    readonly enabled?: boolean;
+    /** Route namespace; the endpoints all hang off it. */
+    readonly basePath?: string;
+    /** Default lifetime of a minted integration token, in days. */
+    readonly tokenTtlDays?: number;
+    /**
+     * Wall-clock budget for one question. The endpoint answers within it — with
+     * an escalation when the turn is still running — because the caller's own
+     * timeout is a fixed part of the contract.
+     */
+    readonly requestTimeoutMs?: number;
+    /** Questions answered at the same time, deployment wide. */
+    readonly maxConcurrent?: number;
+    /** Requests one token may make per rolling minute. */
+    readonly requestsPerMinute?: number;
+    /** Ceiling on one request body, in bytes. */
+    readonly maxRequestBytes?: number;
+    /** Ceiling on one inline image attachment, in bytes. */
+    readonly maxAttachmentBytes?: number;
+    /**
+     * Ceiling on the published answer, in characters. The caller posts it into a
+     * ticket comment, whose own budget is smaller than a model's answer, and a
+     * cut made here at a paragraph boundary is readable where the caller's own
+     * silent truncation is not.
+     */
+    readonly maxAnswerCharacters?: number;
 }
 /** What a QA visitor may attach to one message. */
 export interface QaAttachmentsConfig {
@@ -854,6 +1027,7 @@ export interface ResolvedQaSurfaceConfig {
             readonly allowRawToggle: boolean;
             readonly maxBytes: number;
             readonly maxMarkdownRenderBytes: number;
+            readonly maxListingEntries: number;
         };
         readonly subagents: {
             readonly inheritSources: boolean;
@@ -872,6 +1046,40 @@ 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;
+        };
+        readonly documents: {
+            readonly enabled: boolean;
+            readonly template: string;
+        };
+        readonly sourcePriority: {
+            readonly enabled: boolean;
+            readonly template: string;
+        };
+    };
+    readonly integration: {
+        readonly enabled: boolean;
+        readonly basePath: string;
+        readonly tokenTtlDays: number;
+        readonly requestTimeoutMs: number;
+        readonly maxConcurrent: number;
+        readonly requestsPerMinute: number;
+        readonly maxRequestBytes: number;
+        readonly maxAttachmentBytes: number;
+        readonly maxAnswerCharacters: number;
+    };
 }
 /** Which native registry one unified entry came from. */
 export type QaSlashEntryKind = "skill" | "command";
@@ -1038,6 +1246,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;
@@ -1357,7 +1610,9 @@ export interface QaReviewQueueItem {
     readonly feedbackId?: string;
 }
 /** Administrative actions recorded in the audit trail. */
-export type QaAdminAuditAction = "user.created" | "user.updated" | "user.enabled" | "user.disabled" | "authorization.changed" | "subrole.assignment.changed" | "subrole.created" | "subrole.updated" | "subrole.deleted" | "common_capabilities.updated" | "conversation.reviewed" | "conversation.deleted" | "review.updated" | "review.queued" | "admin.settings.updated";
+export type QaAdminAuditAction = "user.created" | "user.updated" | "user.enabled" | "user.disabled"
+/** An operator set a new password for an account that had requested one. */
+ | "user.password-reset" | "authorization.changed" | "subrole.assignment.changed" | "subrole.created" | "subrole.updated" | "subrole.deleted" | "common_capabilities.updated" | "conversation.reviewed" | "conversation.deleted" | "review.updated" | "review.queued" | "admin.settings.updated" | "skill.created" | "skill.updated" | "skill.deleted";
 export interface QaAdminAuditEvent {
     readonly id: string;
     readonly timestamp: string;
@@ -1614,7 +1869,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.11.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-plugin-kit": "^0.3.0",
-    "@yadsh/dsh-plugin-log": "^0.4.0"
+    "@yadsh/dsh-audit-ui": "^0.1.0",
+    "@yadsh/dsh-documents": "^0.5.0",
+    "@yadsh/dsh-plugin-log": "^0.4.0",
+    "@yadsh/dsh-plugin-kit": "^0.3.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",