@yadsh/dsh-qa-surface 0.11.1 → 0.12.0

package/lib/types/client/settings/sections.d.ts

@@ -15,6 +15,7 @@ export { AccessSection } from "./sections/access.js";
 export { AccountsSection } from "./sections/accounts.js";
 export { AttachmentsSection } from "./sections/attachments.js";
 export { BrandingSection } from "./sections/branding.js";
+export { DocsSection } from "./sections/docs.js";
 export { EmbeddingSection } from "./sections/embedding.js";
 export { InterfaceSection } from "./sections/interface.js";
 export { LockdownSection } from "./sections/lockdown.js";

package/lib/types/client/slash/palette-rows.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Grouping for the palette's rows.
+ *
+ * Ranking is global: skills and commands are scored and sorted together, so
+ * `/tkp` can put a command between two skills and a palette that captioned
+ * every neighbouring run would draw «Навыки» twice over one group of rows.
+ *
+ * This module is the translation between the two: it buckets the ranked rows
+ * by kind, keeps each bucket in ranked order, and puts the bucket whose best
+ * row ranked highest first. The palette's first row is therefore still the
+ * best match — which is the row Enter picks when the user types nothing else.
+ *
+ * A row keeps its `index` from the ranked list, so what the keyboard moves
+ * through is the order the palette draws: the navigation hook publishes the
+ * flattened groups rather than the raw ranking.
+ *
+ * Pure on purpose: the hook and the component both need the same grouping, and
+ * the tests drive it with plain arrays.
+ */
+import type { QaSlashCatalogEntry } from "../../types.js";
+/** One palette row: the entry, and where it sat in the ranked list. */
+export interface QaSlashPaletteRow {
+    readonly entry: QaSlashCatalogEntry;
+    /** Position in the ranked list these groups were built from. */
+    readonly index: number;
+}
+/** One titled group of the palette: exactly one per kind that was ranked. */
+export interface QaSlashPaletteGroup {
+    readonly kind: QaSlashCatalogEntry["kind"];
+    readonly rows: readonly QaSlashPaletteRow[];
+}
+/**
+ * Bucket ranked rows by kind, one group per kind.
+ *
+ * A kind with no row contributes no group, and the group order follows the
+ * ranking (the best row's own kind leads) rather than a fixed
+ * skill-then-command order, so the top of the list never disagrees with the
+ * ranking above it.
+ */
+export declare function groupPaletteRows(rows: readonly QaSlashCatalogEntry[]): readonly QaSlashPaletteGroup[];
+/** The entries of every group, in the order the palette draws them. */
+export declare function flattenPaletteGroups(groups: readonly QaSlashPaletteGroup[]): readonly QaSlashCatalogEntry[];
+//# sourceMappingURL=palette-rows.d.ts.map

package/lib/types/client/turn-sources.d.ts

@@ -9,6 +9,20 @@ export declare function chatLegacyOf(snapshot: ConversationSnapshot | undefined)
  * and replay and requires no assistant-authored bibliography.
  */
 export declare function projectTurnSources(snapshot: ConversationSnapshot | undefined, sessionId?: string, workspaceRoot?: string): readonly QaTurnSources[];
+/**
+ * The directory a projected source path is anchored on: the chat's own cwd.
+ *
+ * Both channels read the same durable tool results, and the Host's evidence —
+ * the set the source preview checks a request against — canonicalizes every
+ * recorded path against the session's own cwd. A projection anchored on
+ * anything else splits one file into two spellings the moment the two
+ * directories differ (an adopted chat, a chat whose cwd was pinned under an
+ * older configuration): the rail then shows a path the Host does not hold, and
+ * the detailed view refuses a source the answer just cited as no longer
+ * evidence until the rail is rebuilt from the Host's own bundles. The
+ * configured pin stays the fallback for a chat the browser cannot place yet.
+ */
+export declare function sourceAnchorRoot(chatCwd: string | undefined, configuredCwd: string | null): string | undefined;
 /** Visible evidence sources for the latest turn, shared by the drawer/footer. */
 export declare function projectSources(snapshot: ConversationSnapshot | undefined, sessionId?: string, workspaceRoot?: string): readonly QaSource[];
 //# sourceMappingURL=turn-sources.d.ts.map

package/lib/types/config-resolvers/integration.d.ts

@@ -3,8 +3,14 @@ type ResolvedIntegration = ResolvedQaSurfaceConfig["integration"];
 /** Operator-tunable bounds; the values the settings card shows as hard limits. */
 export declare const QA_INTEGRATION_TTL_DAYS_MIN = 1;
 export declare const QA_INTEGRATION_TTL_DAYS_MAX = 3650;
+/**
+ * The operator may choose any wait Node can represent faithfully. The former
+ * ten-minute product ceiling cut off legitimate long analyses, while values
+ * above the runtime ceiling wrap to an almost immediate timer.
+ */
 export declare const QA_INTEGRATION_TIMEOUT_MS_MIN = 5000;
-export declare const QA_INTEGRATION_TIMEOUT_MS_MAX = 600000;
+/** Largest delay Node schedules without overflowing to an immediate timer. */
+export declare const QA_INTEGRATION_TIMEOUT_MS_MAX = 2147483647;
 export declare const QA_INTEGRATION_CONCURRENCY_MIN = 1;
 export declare const QA_INTEGRATION_CONCURRENCY_MAX = 16;
 export declare const QA_INTEGRATION_RATE_MIN = 1;

package/lib/types/config-resolvers/shared.d.ts

@@ -7,6 +7,14 @@ export declare function optionalText(value: string | null | undefined): string |
  * Windows-style root is not a mistake to reject on a POSIX host.
  */
 export declare function isAbsoluteDirectoryPath(value: string): boolean;
+/**
+ * Shared numeric guard for a limit with a floor but no honest ceiling: the value
+ * has to be a safe integer of at least `min`. A ceiling belongs on a budget the
+ * deployment itself spends (bytes, parallel calls); a wait it merely allows is
+ * the operator's call, and a ceiling there only ever truncated a legitimate long
+ * answer.
+ */
+export declare function assertIntAtLeast(name: string, value: number, min: number): void;
 /**
  * Shared numeric guard for operator-tuned limits: the value has to be a safe
  * integer inside [min, max], and every rejection carries the same message.

package/lib/types/config-resolvers/tools.d.ts

@@ -2,5 +2,14 @@ import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
 type ToolsSlice = ResolvedQaSurfaceConfig["tools"];
 /** Resolve the QA tool delivery domain: activation trigger, policy, and scope. */
 export declare function resolveTools(input: QaSurfaceConfig): ToolsSlice;
+/**
+ * The version one search runs under, or `""` when the deployment's default is
+ * off, unset, or not what the call is about.
+ *
+ * The readers take a single fallback, and a switch that is off must not fall
+ * back at all — the value stays configured for the day it is turned on, and an
+ * enabled-but-empty pair is simply no default.
+ */
+export declare function docsDefaultVersionOf(tools: ResolvedQaSurfaceConfig["tools"]): string;
 export {};
 //# sourceMappingURL=tools.d.ts.map

package/lib/types/launch-token.d.ts

@@ -12,9 +12,16 @@ interface AuthenticatedUrlFace {
     authenticatedUrl?(baseUrl: string): string;
 }
 /**
- * Resolve the launch token once per process (it is stable for the process
- * lifetime); a missing connection service or an unusable answer warns once
- * and permanently disables the bridge instead of retrying per request.
+ * Resolve the launch token lazily, on the navigations that need it.
+ *
+ * A token that resolved is cached — it is stable for the process lifetime, so
+ * the host is asked once. A failure is **not** cached: the first `/qa` request
+ * can arrive while the plugin tree is still starting, when `connection` is not
+ * answerable yet, and treating that single early answer as final used to leave
+ * every later cookie-less browser on the marker hand-off, which dead-ends at
+ * the host's token screen until the next restart. The failure is reported once
+ * per reason and retried quietly afterwards, so the retry costs a service
+ * lookup and never a log flood.
  */
 export declare function makeLaunchTokenSource(getConnection: () => AuthenticatedUrlFace | undefined, warn: (message: string) => void): LaunchTokenSource;
 export {};

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

@@ -9,7 +9,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 = "3";
-/** One QA tool reports the activation state of whichever agent calls it. */
+/** What the catalog's definitions read, beyond the execution record. */
 export interface QaToolsSelfcheckDeps {
     readonly catalogVersion: string;
     readonly activationMode: string;
@@ -19,6 +19,16 @@ export interface QaToolsSelfcheckDeps {
     readonly activeTools: (agent: Agent) => readonly string[];
     /** Whether the calling agent's session shows the activation skill was loaded. */
     readonly skillLoaded: (agent: Agent) => boolean;
+    /**
+     * Documentation root the two readers use, or `""` for the `docs/` directory
+     * inside each chat's own workspace.
+     */
+    readonly docsRoot?: string | (() => string);
+    /**
+     * Version a search without `version` and without `path` stays inside, or `""`
+     * for a search across every edition the corpus carries.
+     */
+    readonly docsDefaultVersion?: string | (() => string);
 }
 /**
  * Build the shipped QA tool catalog.

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

@@ -19,6 +19,14 @@ import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
  * names are accepted as filters. A path the convention does not describe is
  * still searched and still read — it simply carries no identity.
  *
+ * A real corpus also carries its own working material: the stand publishes an
+ * asset tree, inventories and triage notes beside the documents, under leading
+ * underscores. None of that is what a question is asked about, and an inventory
+ * names every module and version there is, so a walk that met it first spent the
+ * whole answer on it. The walk therefore visits the documented modules first,
+ * loose files next, and the underscored service material last — searched, but
+ * never at the expense of the documents.
+ *
  * Nothing here is destructive and building it registers nothing: like the rest
  * of the catalog these are side-effect-free definitions, and the workspace root
  * is read from `exec.agent` at call time.
@@ -54,11 +62,32 @@ interface QaDocsExecution {
         };
     };
 }
+/**
+ * Where this deployment publishes its documentation.
+ *
+ * A deployment that hands every chat its own workspace publishes documentation
+ * inside it, and an empty `root` keeps that layout. One that publishes the
+ * corpus once — outside every per-user directory — names it here, and the tools
+ * read it exactly as they read a per-chat tree: same fence, same reported paths
+ * (`docs/<module>/<version>/…`), only the directory that contains the tree
+ * comes from configuration instead of from the calling chat.
+ */
+export interface QaDocsOptions {
+    /** Absolute documentation root, or `""` for `<chat workspace>/docs`. */
+    readonly root?: string;
+    /**
+     * Documentation version a search stays inside when the caller named neither
+     * `version` nor `path`; `""` (the default) leaves every edition in scope. The
+     * deployment sets it so a chat's questions do not have to carry the stand's
+     * edition, and an explicit `version` or `path` still decides for itself.
+     */
+    readonly defaultVersion?: string;
+}
 /** The resolved documentation root of one call. */
 export interface QaDocsRoot {
-    /** Canonical workspace root of the calling chat. */
+    /** Canonical directory the tree sits in: the chat's workspace, or the configured root's parent. */
     readonly workspace: string;
-    /** Canonical `<workspace>/docs`. */
+    /** Canonical directory documentation is read from. */
     readonly docs: string;
 }
 /**
@@ -116,8 +145,12 @@ export declare function docsIdentityOf(pathFromDocsRoot: string): QaDocsIdentity
  * The root is a real directory inside the canonical workspace: a `docs` entry
  * that is a link or a file is refused rather than followed, because the fence
  * is the point of the tool and a link is how a fence is left.
+ *
+ * A deployment that names its corpus once (`QaDocsOptions.root`) skips the
+ * per-chat lookup entirely — that layout is exactly why it configures the root —
+ * and is held to the same rules: absolute, a real directory, no links.
  */
-export declare function docsRootOf(exec: QaDocsExecution): Promise<QaDocsRoot>;
+export declare function docsRootOf(exec: QaDocsExecution, options?: QaDocsOptions): Promise<QaDocsRoot>;
 export interface QaDocsSearchRequest {
     readonly query: string;
     readonly version?: string | undefined;
@@ -153,8 +186,8 @@ export declare function readDocumentation(root: QaDocsRoot, request: QaDocsReadR
  * version/module facets exist so a model that has been told "3.8" stops
  * sweeping the whole tree.
  */
-export declare function createDocsSearchTool(): ToolDefinition;
+export declare function createDocsSearchTool(options?: QaDocsOptions): ToolDefinition;
 /** `docs_read` — open one documentation file at a bounded window of lines. */
-export declare function createDocsReadTool(): ToolDefinition;
+export declare function createDocsReadTool(options?: QaDocsOptions): ToolDefinition;
 export {};
 //# sourceMappingURL=docs-tools.d.ts.map

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

@@ -8,6 +8,13 @@ export interface QaToolsOptions {
     readonly activationSkill: string;
     readonly activationMode: string;
     readonly activationPresets: readonly string[];
+    /** Documentation root the readers use; `""` reads each chat's own `docs/`. */
+    readonly docsRoot: string | (() => string);
+    /**
+     * Version a search falls back to when the model named neither `version` nor
+     * `path`; `""` searches every edition the corpus carries.
+     */
+    readonly docsDefaultVersion: string | (() => string);
 }
 /**
  * The QA tool subsystem: one catalog, one per-agent activation manager, and the

package/lib/types/shared/docs-version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The documentation version grammar, shared by the Host and the browser half.
+ *
+ * This module must stay dependency-free: the settings card bundle inlines the
+ * resolver that validates a configured default version, and a browser build
+ * must not pull the QA tool runtime — or the Node builtins it reads files with
+ * — into the page just to learn what a version looks like.
+ */
+/**
+ * Whether a path segment — or a configured default version — is a documentation
+ * version. A default the corpus can never match is refused where it is written
+ * rather than answered with an empty search.
+ */
+export declare function isDocumentationVersion(value: string): boolean;
+//# sourceMappingURL=docs-version.d.ts.map

package/lib/types/types.d.ts

@@ -714,6 +714,28 @@ export interface QaSurfaceConfig {
          * name the QA preset in any deployment that composes more than one.
          */
         readonly activationPresets?: readonly string[];
+        /**
+         * Absolute path of the documentation tree `docs_search`/`docs_read` read.
+         * Leave it empty when the deployment publishes `docs/` inside each chat's
+         * own workspace; name it when the corpus is published once, outside every
+         * per-user directory, which is otherwise unreadable to those tools.
+         */
+        readonly docsRoot?: string;
+        /**
+         * Documentation version `docs_search` stays inside when the model named
+         * neither `version` nor `path`. A corpus carries several editions of the
+         * same module, and a chat asked about "the product" answers out of whichever
+         * edition it happened to read first; naming the stand's edition here lets a
+         * search default to it, and an explicit `version` or `path` still decides
+         * for itself.
+         */
+        readonly docsDefaultVersion?: string;
+        /**
+         * Whether `docsDefaultVersion` is applied. The value stays configured while
+         * the switch is off, so a stand can turn the default back on without
+         * retyping it.
+         */
+        readonly docsDefaultVersionEnabled?: boolean;
     };
     readonly lockdown?: {
         readonly enabled?: boolean;
@@ -990,6 +1012,18 @@ export interface ResolvedQaSurfaceConfig {
         readonly activationSkill: string;
         readonly activationMode: QaToolActivationMode;
         readonly activationPresets: readonly string[];
+        /**
+         * Absolute documentation root the QA catalogue reads, or `""` for the
+         * `docs/` directory inside each chat's own workspace.
+         */
+        readonly docsRoot: string;
+        /**
+         * Version a search without `version` and without `path` stays inside, or
+         * `""` for a search across every edition the corpus carries.
+         */
+        readonly docsDefaultVersion: string;
+        /** Whether the deployment's default version is in force. */
+        readonly docsDefaultVersionEnabled: boolean;
     };
     readonly sources: {
         readonly enabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadsh/dsh-qa-surface",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
   "repository": {
     "type": "git",
@@ -133,11 +133,11 @@
   "dependencies": {
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
+    "@yadsh/dsh-documents": "^0.5.1",
     "@yadsh/dsh-audit-core": "^0.1.0",
-    "@yadsh/dsh-audit-ui": "^0.1.0",
-    "@yadsh/dsh-documents": "^0.5.0",
-    "@yadsh/dsh-plugin-kit": "^0.3.0",
-    "@yadsh/dsh-plugin-log": "^0.4.0"
+    "@yadsh/dsh-audit-ui": "^0.1.1",
+    "@yadsh/dsh-plugin-log": "^0.4.0",
+    "@yadsh/dsh-plugin-kit": "^0.3.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.2",