@yadsh/dsh-qa-surface 0.10.0 → 0.11.0

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

@@ -0,0 +1,160 @@
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/**
+ * `docs_search` and `docs_read` — the documentation surface of the QA catalog.
+ *
+ * A QA chat answers questions from the stand's documentation, and until now the
+ * model had no tool that said where that documentation is: the path in a
+ * reviewer's remark (`docs/platform/3.8/…`) was something the model had to
+ * guess its way to with a glob sweep, and a miss read as "the document does
+ * not exist" rather than "wrong tree". These two tools make the tree a
+ * first-class surface. Both are read-only, both are fenced to the
+ * documentation directory inside the calling chat's workspace
+ * (`<session cwd>/docs`, the directory the stand publishes its documentation
+ * into), and both name the documentation as what they search, so the tool
+ * description itself answers "where do I look for documentation?".
+ *
+ * The tree is read as a shallow layout convention, not a schema: hits carry
+ * the `version` and `module` parsed out of the path (`docs/<module>/<version>/…`)
+ * so the model can stay inside one edition of one module, and the same two
+ * names are accepted as filters. A path the convention does not describe is
+ * still searched and still read — it simply carries no identity.
+ *
+ * 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.
+ */
+/** The documentation directory inside a chat workspace. */
+export declare const QA_DOCS_DIRECTORY = "docs";
+/** Search defaults and budgets, all fixed: a chat cannot raise them. */
+export declare const QA_DOCS_SEARCH_DEFAULT_LIMIT = 8;
+export declare const QA_DOCS_SEARCH_MAX_LIMIT = 40;
+export declare const QA_DOCS_SEARCH_BYTE_BUDGET = 4000;
+export declare const QA_DOCS_READ_DEFAULT_LINES = 120;
+export declare const QA_DOCS_READ_MAX_LINES = 400;
+/** Why a documentation tool refused a call. */
+export type QaDocsRefusal = "workspace-unavailable" | "docs-unavailable" | "invalid-request" | "outside-docs" | "symlink-escape" | "not-found" | "not-a-file" | "not-text";
+/**
+ * A typed refusal of one documentation call.
+ *
+ * The message is what the model reads. It names the reason in words and never
+ * echoes an absolute host path, so a refusal cannot leak the deployment's
+ * layout into the conversation.
+ */
+export declare class QaDocsError extends Error {
+    readonly code: QaDocsRefusal;
+    constructor(code: QaDocsRefusal, message: string, options?: ErrorOptions);
+}
+/** The slice of the execution record these tool bodies read. */
+interface QaDocsExecution {
+    readonly agent?: {
+        readonly session: {
+            readonly header: {
+                readonly cwd?: string;
+            };
+        };
+    };
+}
+/** The resolved documentation root of one call. */
+export interface QaDocsRoot {
+    /** Canonical workspace root of the calling chat. */
+    readonly workspace: string;
+    /** Canonical `<workspace>/docs`. */
+    readonly docs: string;
+}
+/**
+ * Module/version identity parsed out of a documentation path.
+ *
+ * Both are optional and, when a path does not carry one, genuinely absent: the
+ * catalog's output schema is read with `exactOptionalPropertyTypes`, so an
+ * identity is spread into a report rather than written as `undefined`.
+ */
+export interface QaDocsIdentity {
+    readonly version?: string;
+    readonly module?: string;
+}
+/** One documentation match. */
+export interface QaDocsHit extends QaDocsIdentity {
+    /** Workspace-relative path, starting at `docs/`, with forward slashes. */
+    readonly path: string;
+    /** 1-based line number inside the file. */
+    readonly line: number;
+    /** The matched line, trimmed and bounded. */
+    readonly text: string;
+}
+/** The outcome of one documentation search. */
+export interface QaDocsSearchResult extends QaDocsIdentity {
+    readonly query: string;
+    /** The directory documentation is read from, relative to the workspace. */
+    readonly root: string;
+    readonly hits: QaDocsHit[];
+    readonly truncated: boolean;
+    readonly filesScanned: number;
+    readonly skipped: number;
+}
+/** The outcome of one documentation read. */
+export interface QaDocsReadResult extends QaDocsIdentity {
+    readonly path: string;
+    readonly from: number;
+    readonly to: number;
+    readonly totalLines: number;
+    readonly truncated: boolean;
+    readonly text: string;
+}
+/**
+ * Identity of one documentation path, read relative to the documentation root.
+ *
+ * The documented layout is `docs/<module>/<version>/…`: the version is the
+ * first directory segment that parses as one (`3.8`, `v2`, `2024.1`), and the
+ * module is the directory segment immediately before it. A path with no
+ * version segment keeps its first directory segment as the module; a file
+ * directly in `docs/` carries neither, and is still searched and read.
+ */
+export declare function docsIdentityOf(pathFromDocsRoot: string): QaDocsIdentity;
+/**
+ * The canonical documentation root of one call.
+ *
+ * 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.
+ */
+export declare function docsRootOf(exec: QaDocsExecution): Promise<QaDocsRoot>;
+export interface QaDocsSearchRequest {
+    readonly query: string;
+    readonly version?: string | undefined;
+    readonly module?: string | undefined;
+    readonly path?: string | undefined;
+    readonly limit?: number | undefined;
+}
+/**
+ * Search the documentation tree of one chat workspace.
+ *
+ * Matching is a case-insensitive substring test, line by line: a hit is a
+ * line, not a file, so the caller can cite it. The result is bounded twice —
+ * by `limit` hits and by the byte budget of the rendered report — and reports
+ * which bound cut it short instead of silently dropping matches.
+ * @throws QaDocsError when the tree is missing, the scope path is wrong, or the query is empty.
+ */
+export declare function searchDocumentation(root: QaDocsRoot, request: QaDocsSearchRequest): Promise<QaDocsSearchResult>;
+export interface QaDocsReadRequest {
+    readonly path: string;
+    readonly from?: number | undefined;
+    readonly lines?: number | undefined;
+}
+/**
+ * Read one window of one documentation file of a chat workspace.
+ * @throws QaDocsError when the path is outside the tree, missing, a directory, or not text.
+ */
+export declare function readDocumentation(root: QaDocsRoot, request: QaDocsReadRequest): Promise<QaDocsReadResult>;
+/**
+ * `docs_search` — the catalog's documentation search.
+ *
+ * The description is part of the tool's job: it states that documentation is
+ * read here, from `docs/`, and that memory is not a documentation source. The
+ * version/module facets exist so a model that has been told "3.8" stops
+ * sweeping the whole tree.
+ */
+export declare function createDocsSearchTool(): ToolDefinition;
+/** `docs_read` — open one documentation file at a bounded window of lines. */
+export declare function createDocsReadTool(): ToolDefinition;
+export {};
+//# sourceMappingURL=docs-tools.d.ts.map

package/lib/types/secure-session.d.ts

@@ -14,6 +14,13 @@ export interface QaAccountsGate {
         readonly id: string;
     } | undefined;
     userWorkspace(userId: string, registeredWorkspacePath: string): string;
+    /**
+     * The account an ownership record names, for callers that authenticated by
+     * another credential (the integration API's service token). Absent records
+     * and a changed owner both resolve to undefined. Only read by that path: the
+     * token-shaped entry above remains the browser's only door.
+     */
+    ownerIdOf(sessionId: string): string | undefined;
 }
 /**
  * Host-side QA policy admission boundary — the only browser-callable operation
@@ -48,6 +55,11 @@ export declare class QaPolicyAdmission {
      */
     private readonly attested;
     private readonly workspaceAccess;
+    /**
+     * Removers of the document input roots granted per session, so a grant lives
+     * exactly as long as the workspace access that justified it.
+     */
+    private readonly documentInputRoots;
     /**
      * Every name reachable anywhere in one QA conversation, keyed by session id.
      *
@@ -67,7 +79,9 @@ export declare class QaPolicyAdmission {
      */
     dynamicToolNames?: (agent: Agent) => readonly string[], 
     /** Resolve and freeze the session's subrole policy after its agent exists. */
-    capabilityPolicy?: ((token: string, sessionId: string, agent: Agent) => Promise<QaResolvedSessionPolicy | undefined>) | undefined, 
+    capabilityPolicy?: ((owner: {
+        readonly id: string;
+    } | undefined, sessionId: string, agent: Agent) => Promise<QaResolvedSessionPolicy | undefined>) | undefined, 
     /** Scope-local catalog entries may be known before they are activated. */
     knownDynamicToolNames?: () => readonly string[]);
     /**
@@ -92,6 +106,20 @@ export declare class QaPolicyAdmission {
      * Source preview asks for the same root, so one upload is readable by both.
      */
     attachmentRoot(): string | undefined;
+    /**
+     * Carry the fence's attachment exemption into the document pipeline.
+     *
+     * The guard above lets a single-file read reach the mounted store: an upload
+     * is content-addressed, immutable, outside every workspace, and the prompt
+     * hands the model exactly that path. The document pipeline keeps its own
+     * read scope and knew nothing about the store, so `document_*` refused the
+     * very file the model was allowed to read — the panel's own Word preview hit
+     * the same wall. The grant is the missing hand-over, made where the access it
+     * mirrors is made: per admitted session, and revoked with it.
+     */
+    private grantDocumentInputRoots;
+    /** Drop one session's document grant, if the pipeline still holds it. */
+    private revokeDocumentInputRoots;
     /**
      * The live agent for one session, resuming a Session the Host has not
      * materialized in this process.
@@ -127,6 +155,29 @@ export declare class QaPolicyAdmission {
      */
     private accessOwner;
     secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
+    /**
+     * The same admission for a caller whose account was already authenticated by
+     * another credential — the integration API, which has a service token and no
+     * browser session.
+     *
+     * Everything after identity is shared with {@link secureSession}: the
+     * policy pins, the tool allow-list, the QA tool attachment and the
+     * attestation record are one code path, because a second copy of admission
+     * would be a second place for a QA chat to be admitted without them.
+     *
+     * @param userId - the account the credential resolved to.
+     * @param sessionId - the session to attest.
+     * @returns the sanitized proof, as the browser path receives it.
+     */
+    secureSessionForUser(userId: string, sessionId: string): Promise<QaLockdownProof>;
+    /**
+     * The account behind one session, taken from the ownership record rather
+     * than from a token. The record is the same authority the token path reads:
+     * a chat belongs to exactly one account, and a service token may only ever
+     * reach the chats of its own.
+     */
+    private ownerById;
+    private secureSessionAs;
     /**
      * Mask one agent down to the policy's tool names, for the account-free path
      * (a capability policy installs its own mask through its grants).

package/lib/types/shared/integration-tokens.d.ts

@@ -0,0 +1,24 @@
+import type { QaServiceTokenScope } from "../types.js";
+/**
+ * The integration-token vocabulary and its bounds, on the browser side too.
+ *
+ * Minting lives in `accounts/service-token.ts`, which is Host-only (it hashes a
+ * secret before storing it); the profile page has to name the same scopes and
+ * enforce the same limits without importing that. Dependency-free like every
+ * `src/shared` module, so both bundles inline it and there is exactly one copy
+ * of the numbers the two halves have to agree on.
+ */
+/**
+ * What an integration token may do. Scopes are checked per request rather than
+ * per deployment: the same bridge token that asks questions carries no
+ * permission to read back a conversation catalog it was not given.
+ */
+export declare const QA_SERVICE_TOKEN_SCOPES: readonly QaServiceTokenScope[];
+/** A token that carries no scope is useless; `ask` is what the API is for. */
+export declare const QA_SERVICE_TOKEN_DEFAULT_SCOPES: readonly QaServiceTokenScope[];
+/** Bounds the caller's label; it is a note to the operator, not a document. */
+export declare const QA_SERVICE_TOKEN_LABEL_MAX = 80;
+/** Bounds on a token's life; zero or a negative TTL would mint a dead token. */
+export declare const QA_SERVICE_TOKEN_TTL_DAYS_MIN = 1;
+export declare const QA_SERVICE_TOKEN_TTL_DAYS_MAX = 3650;
+//# sourceMappingURL=integration-tokens.d.ts.map

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 {
@@ -528,6 +629,16 @@ export interface QaNotesConfig {
         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;
@@ -710,6 +821,42 @@ 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 {
@@ -913,6 +1060,25 @@ export interface ResolvedQaSurfaceConfig {
             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. */
@@ -1444,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadsh/dsh-qa-surface",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
   "repository": {
     "type": "git",
@@ -135,9 +135,9 @@
     "zod": "^4.4.3",
     "@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"
+    "@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",