@yadsh/dsh-qa-surface 0.11.0 → 0.11.2

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;
+/**
+ * Floor only: how long an integration may wait for its answer is the operator's
+ * call. The deployment spends no budget of its own by waiting, and the ceiling
+ * this constant used to carry (10 minutes) truncated exactly the long questions
+ * an integration exists for — a nineteen-minute analysis came back as
+ * "escalate" while the answer was still being written.
+ */
 export declare const QA_INTEGRATION_TIMEOUT_MS_MIN = 5000;
-export declare const QA_INTEGRATION_TIMEOUT_MS_MAX = 600000;
 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/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,11 @@ 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;
 }
 /**
  * Build the shipped QA tool catalog.

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

@@ -54,11 +54,25 @@ 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;
+}
 /** 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 +130,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 +171,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,8 @@ 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;
 }
 /**
  * The QA tool subsystem: one catalog, one per-agent activation manager, and the

package/lib/types/types.d.ts

@@ -714,6 +714,13 @@ 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;
     };
     readonly lockdown?: {
         readonly enabled?: boolean;
@@ -990,6 +997,11 @@ 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;
     };
     readonly sources: {
         readonly enabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadsh/dsh-qa-surface",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
   "repository": {
     "type": "git",
@@ -134,9 +134,9 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "@yadsh/dsh-audit-core": "^0.1.0",
-    "@yadsh/dsh-audit-ui": "^0.1.0",
-    "@yadsh/dsh-documents": "^0.5.0",
+    "@yadsh/dsh-documents": "^0.5.1",
     "@yadsh/dsh-plugin-log": "^0.4.0",
+    "@yadsh/dsh-audit-ui": "^0.1.1",
     "@yadsh/dsh-plugin-kit": "^0.3.0"
   },
   "devDependencies": {