@yadsh/dsh-qa-surface 0.6.1 → 0.7.0

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

@@ -15,7 +15,6 @@ 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 { DocumentsSection } from "./sections/documents.js";
 export { EmbeddingSection } from "./sections/embedding.js";
 export { InterfaceSection } from "./sections/interface.js";
 export { LockdownSection } from "./sections/lockdown.js";

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

@@ -1,7 +1,7 @@
 import type { ClientRemote } from "@deepseek-ai/dsh-api-gateway/client";
 import type { ISessions, SessionFace } from "@deepseek-ai/dsh-api-session-controller/client";
 import type { UiConversation } from "@deepseek-ai/dsh-client-ui-conversation/client";
-import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountStarter, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSessionState, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaTurnSources, QaWhoamiResult } from "../types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountStarter, QaAccountUserPublic, QaAccessAdminSnapshot, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSessionState, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaTurnSources, QaWhoamiResult, QaCapabilitySelection, QaCurrentAccess, QaSessionAccess, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaConversationDetail, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaUserQuery } from "../types.js";
 /** Wire content one prompt carries: text plus base64 image uploads. */
 export type QaPromptContent = Parameters<SessionFace["prompt"]>[0];
 /** DSH session runtime surface the QA controller is allowed to touch. */
@@ -29,7 +29,44 @@ export type QaSecureSession = (token: string, sessionId: string) => Promise<{
     readonly error: unknown;
 }>;
 /** Host-authoritative creation: identity, cwd and policy never come from the browser. */
-export type QaCreateSession = (token: string) => Promise<RemoteResult<string>>;
+export type QaCreateSession = (token: string, subroleId: string | null, adminPreview: boolean) => Promise<RemoteResult<string>>;
+/** Role selector plus administrator mutation channel. */
+export interface QaAccessApi {
+    current(token: string): Promise<RemoteResult<QaCurrentAccess>>;
+    session(token: string, sessionId: string): Promise<RemoteResult<QaSessionAccess>>;
+    admin(token: string): Promise<RemoteResult<QaAccessAdminSnapshot>>;
+    createSubrole(token: string, input: QaSubrole): Promise<RemoteResult<QaSubrole>>;
+    updateSubrole(token: string, id: string, input: QaSubrole): Promise<RemoteResult<QaSubrole>>;
+    deleteSubrole(token: string, id: string, replacementId: string | null): Promise<RemoteResult<{
+        readonly deleted: boolean;
+    }>>;
+    updateCommon(token: string, input: QaCapabilitySelection): Promise<RemoteResult<QaCapabilitySelection>>;
+    updateAssignment(token: string, userId: string, input: QaUserAccess): Promise<RemoteResult<QaUserAccess>>;
+    updateSkillOverride(token: string, input: QaSkillAssignmentOverride): Promise<RemoteResult<readonly QaSkillAssignmentOverride[]>>;
+    skillActivations(token: string, sessionId: string): Promise<RemoteResult<readonly QaSkillActivationRecord[]>>;
+}
+/**
+ * The administrative console's wire surface. Every call carries the caller's
+ * token and nothing else identifying: the Host resolves the actor, checks the
+ * permission the method needs and answers with the audience-safe refusal code
+ * the page renders.
+ */
+export interface QaAdminApi {
+    overview(token: string): Promise<RemoteResult<QaAdminOverview>>;
+    users(token: string, query: QaUserQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaAdminUserRow>>>;
+    user(token: string, userId: string): Promise<RemoteResult<QaAdminUserDetail>>;
+    updateUser(token: string, userId: string, update: QaAdminUserUpdate): Promise<RemoteResult<QaAdminUserDetail>>;
+    conversations(token: string, query: QaConversationQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaConversationSummary>>>;
+    conversation(token: string, conversationId: string): Promise<RemoteResult<QaConversationDetail>>;
+    feedback(token: string, query: QaFeedbackQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaFeedbackRow>>>;
+    /** The signed-in user's own verdict on one of their assistant messages. */
+    rateMessage(token: string, conversationId: string, messageId: string, input: QaMessageFeedbackInput): Promise<RemoteResult<QaMessageFeedback>>;
+    reviewQueue(token: string, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaReviewQueueRow>>>;
+    queueConversation(token: string, conversationId: string, messageId: string | null): Promise<RemoteResult<QaReviewQueueItem>>;
+    saveReview(token: string, input: QaConversationReviewInput): Promise<RemoteResult<QaConversationReview>>;
+    metrics(token: string): Promise<RemoteResult<QaQualityMetrics>>;
+    audit(token: string, query: QaAuditQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaAdminAuditEvent>>>;
+}
 /**
  * Browser file-upload service (`ctx.fileUpload`), described structurally on
  * purpose: files do not ride the prompt inline the way images do, they are

package/lib/types/enforcement/skill-policy.d.ts

@@ -0,0 +1,29 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { SkillSummary } from "@deepseek-ai/dsh-skill";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaEffectiveCapabilityPolicy } from "../types.js";
+import type { QaAgentToolGrants } from "./tool-grants.js";
+declare const SKILL_NOT_AVAILABLE = "SKILL_NOT_AVAILABLE";
+export interface QaSkillPolicyOptions {
+    readonly agent: Agent;
+    readonly policy: QaEffectiveCapabilityPolicy;
+    readonly discovered: ReadonlyMap<string, SkillSummary>;
+    /** The agent's live tool policy; loading a skill may widen it. */
+    readonly grants: QaAgentToolGrants;
+    readonly logger: PluginLogger;
+    /** Preview sessions exercise the real policy and label their own records. */
+    readonly preview?: boolean;
+}
+/**
+ * Agent-local skill consumer. The local `skill` registration shadows the
+ * standard loader; discovery, direct loading and a `/name` gesture all enforce
+ * the same frozen allow-list, and every successful load activates the tool
+ * grant the skill declares — still capped by the subrole's ceiling.
+ *
+ * Loading the instructions and widening the toolset is one operation: a skill
+ * that cannot be granted what it requires is refused instead of being handed
+ * instructions it has no tools to follow.
+ */
+export declare function installQaSkillPolicy(options: QaSkillPolicyOptions): () => void;
+export { SKILL_NOT_AVAILABLE };
+//# sourceMappingURL=skill-policy.d.ts.map

package/lib/types/enforcement/tool-grants.d.ts

@@ -0,0 +1,84 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaSkillActivationOrigin, QaSkillActivationRecord, QaSkillDescriptor } from "../types.js";
+/** One live grant: the skill that asked for tools and what it actually got. */
+export interface QaSkillGrant {
+    readonly skillName: string;
+    readonly origin: QaSkillActivationOrigin;
+    readonly requestedTools: readonly string[];
+    readonly grantedTools: readonly string[];
+    readonly deniedTools: readonly string[];
+    readonly activatedAt: string;
+}
+export type QaSkillActivationOutcome = {
+    readonly status: "activated";
+    readonly grant: QaSkillGrant;
+    /** Present when a best-effort skill had to give up a required tool. */
+    readonly warning?: string;
+} | {
+    readonly status: "rejected";
+    readonly reason: string;
+};
+export interface QaAgentToolGrantsOptions {
+    readonly agent: Agent;
+    /** Tools visible from the first model step; the restriction keeps admitting them. */
+    readonly baseTools: readonly string[];
+    /** Ceiling for grants, already narrowed to tools that exist right now. */
+    readonly grantableTools: readonly string[];
+    /** Normalized `metadata.qa-surface` of every discovered skill. */
+    readonly descriptors: ReadonlyMap<string, QaSkillDescriptor>;
+    readonly logger: PluginLogger;
+    /** Append one attempt to the session record for later review. */
+    readonly record?: (entry: QaSkillActivationRecord) => void;
+}
+/**
+ * The scoped tool policy of one live agent.
+ *
+ * Two independent layers enforce the same effective set. `restrict()` decides
+ * what the model can see at the next step, and the admission's guard decides
+ * what may actually run; a grant widens both, and only up to the ceiling the
+ * subrole was configured with. A skill file can therefore ask for anything —
+ * the intersection with the role ceiling is what it gets.
+ *
+ * A restriction may only name tools the scope inherits, so a grant is verified
+ * by applying it: a name the registry refuses (agent-local, unregistered) is
+ * dropped from the grant instead of breaking the session.
+ */
+export declare class QaAgentToolGrants {
+    private readonly options;
+    private readonly active;
+    private readonly tools;
+    private disposeRestriction;
+    constructor(options: QaAgentToolGrantsOptions);
+    /** Whether the model would see this tool right now. */
+    effectiveTools(): ReadonlySet<string>;
+    /** Grants currently held, newest last; one entry per activated skill. */
+    activeGrants(): readonly QaSkillGrant[];
+    /**
+     * Activate one skill's declared tool requirements.
+     *
+     * The whole operation is atomic from the caller's point of view: either the
+     * grant is recorded and the restriction admits it, or nothing changed and
+     * the reason is returned. A strict skill refuses the activation outright; a
+     * best-effort one activates and reports what it had to give up.
+     * @param skillName - the skill the agent asked to load.
+     * @param origin - which activation path asked, for the session record.
+     * @returns the outcome, including the model-facing reason on refusal.
+     */
+    activate(skillName: string, origin: QaSkillActivationOrigin): QaSkillActivationOutcome;
+    /** Record an audience refusal; no tool state changes. */
+    deny(skillName: string, origin: QaSkillActivationOrigin, reason: string): void;
+    /** Lift the restriction this instance owns. Safe to call more than once. */
+    dispose(): void;
+    /**
+     * Swap the scoped restriction, newest first.
+     *
+     * The new mask is installed before the previous one is lifted: restrictions
+     * intersect, so lifting first would leave a window in which the agent is
+     * unrestricted, and a rejected name would then leave it that way.
+     */
+    private applyRestriction;
+    private restore;
+    private commit;
+}
+//# sourceMappingURL=tool-grants.d.ts.map

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import type { Context } from "@deepseek-ai/cordis";
 import type { QaTurnSources } from "./provenance/types.js";
-import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaPrincipal } from "./types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaPrincipal, QaAccessAdminSnapshot, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaCapabilitySelection, QaConversationDetail, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaCurrentAccess, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSessionAccess, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, QaUserQuery } from "./types.js";
 export declare const name = "qa-surface";
 export declare const inject: string[];
 import { QA_SURFACE_SETTINGS_NAMESPACE } from "./shared/settings.js";
@@ -27,6 +27,13 @@ export declare class QaSurface extends TypertRemoteService {
     private readonly tools;
     /** Account-remote bodies; the wire signatures stay on this class. */
     private readonly accountRemotes;
+    /** Roles, assignments, discovery and immutable per-session capability sets. */
+    private readonly access;
+    /**
+     * The administrative console: authorization, conversation queries over
+     * stored logs, quality records and their aggregations.
+     */
+    private readonly admin;
     /** Personal skills: storage, the DSH provider and the manual-edit watcher. */
     private readonly personalSkills;
     /** Personal-skill remote bodies; the wire signatures stay on this class. */
@@ -38,13 +45,13 @@ export declare class QaSurface extends TypertRemoteService {
     private disposeRoute;
     private routeKey;
     /**
-     * The document subsystem: its own runtime and the four tool registrations.
-     * Rebuilt when the document configuration changes and torn down while the
-     * subsystem or the whole surface is disabled.
+     * The quality store opens its file on first use, so a deployment that never
+     * opens the admin console never grows one.
      */
-    private documents;
-    private documentsKey;
+    private qualityStore;
     constructor(ctx: Context, entry?: QaSurfaceConfig);
+    /** The quality store, opening its file the first time anyone needs it. */
+    private quality;
     /** Resolve browser authentication to the caller only; never accepts an id. */
     principalForToken(token: string): QaPrincipal | undefined;
     /** Resolve only a directly QA-owned root session; delegated children fail closed. */
@@ -101,7 +108,45 @@ export declare class QaSurface extends TypertRemoteService {
      * cwd is `<configured workspace>/.qa-users/<account UUID>` and the child is
      * intentionally not registered or attached as another DSH workspace.
      */
-    createSession(token: string): Promise<string>;
+    createSession(token: string, subroleId: string | null, adminPreview: boolean): Promise<string>;
+    /** The selector model for the signed-in user; admin grants are irrelevant. */
+    accessCurrent(token: string): QaCurrentAccess;
+    /** The immutable role pinned to an existing session. */
+    accessSession(token: string, sessionId: string): QaSessionAccess;
+    /** Complete administrator projection; authorization is checked before discovery. */
+    accessAdminSnapshot(token: string): Promise<QaAccessAdminSnapshot>;
+    accessCreateSubrole(token: string, input: QaSubrole): QaSubrole;
+    accessUpdateSubrole(token: string, id: string, input: QaSubrole): QaSubrole;
+    accessDeleteSubrole(token: string, id: string, replacementId: string | null): {
+        readonly deleted: boolean;
+    };
+    accessUpdateCommon(token: string, input: QaCapabilitySelection): QaCapabilitySelection;
+    accessUpdateAssignment(token: string, userId: string, input: QaUserAccess): QaUserAccess;
+    /** Layer one administrator assignment over what a SKILL.md declares. */
+    accessUpdateSkillOverride(token: string, input: QaSkillAssignmentOverride): readonly QaSkillAssignmentOverride[];
+    /** What each skill activation actually granted in this session. */
+    accessSkillActivations(token: string, sessionId: string): readonly QaSkillActivationRecord[];
+    /** Counters, attention lines and the newest quality signals. */
+    adminOverview(token: string): Promise<QaAdminOverview>;
+    adminUsers(token: string, query: QaUserQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaAdminUserRow>>;
+    adminUser(token: string, userId: string): Promise<QaAdminUserDetail>;
+    /** Authorization role, status and subrole assignment of one account. */
+    adminUpdateUser(token: string, userId: string, update: QaAdminUserUpdate): Promise<QaAdminUserDetail>;
+    adminConversations(token: string, query: QaConversationQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaConversationSummary>>;
+    /** One conversation with its messages, tool calls and review state. */
+    adminConversation(token: string, conversationId: string): Promise<QaConversationDetail>;
+    adminFeedback(token: string, query: QaFeedbackQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaFeedbackRow>>;
+    /**
+     * Rate one of the caller's own assistant messages. The token names the only
+     * ratable conversation, exactly as the self-service profile write does.
+     */
+    adminRateMessage(token: string, conversationId: string, messageId: string, input: QaMessageFeedbackInput): QaMessageFeedback;
+    adminReviewQueue(token: string, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaReviewQueueRow>>;
+    /** Park a conversation for review without rating it. */
+    adminQueueConversation(token: string, conversationId: string, messageId: string | null): QaReviewQueueItem;
+    adminSaveReview(token: string, input: QaConversationReviewInput): QaConversationReview;
+    adminMetrics(token: string): Promise<QaQualityMetrics>;
+    adminAudit(token: string, query: QaAuditQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaAdminAuditEvent>>;
     /** Pin and attest the effective policy. The browser supplies identity only. */
     secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
     /** Return canonical Host snapshots from plugin-owned durable provenance. */
@@ -169,13 +214,12 @@ export declare class QaSurface extends TypertRemoteService {
     };
     private refreshRoute;
     /**
-     * Install, rebuild or tear down the document subsystem. The raw entry is
-     * resolved with the documented environment overrides applied, so a
-     * deployment can point `QA_DOCLING_BASE_URL` at its own service without
-     * touching the settings namespace; the settings layer stays authoritative
-     * for everything it declares.
+     * The document pipeline moved out of this plugin into `@yadsh/dsh-documents`.
+     * A deployment whose profile still carries the old `documents` section would
+     * otherwise lose its Docling endpoint and artifact root silently, so the
+     * leftover section is reported once per configuration change instead.
      */
-    private refreshDocuments;
+    private warnDocumentsMoved;
 }
 export { ConfigSchema, DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath, resolveConfig, } from "./config.js";
 export { QaAttestationError } from "./attestation.js";
@@ -185,8 +229,12 @@ export { entryRedirectRow, entryRedirectScript } from "./entry-redirect.js";
 export { registerQaNavigationRoute } from "./host-route.js";
 export { QaIntegrationPrincipalBindings } from "./integration-principals.js";
 export { qaToolDenial, qaToolPolicyPlan } from "./lockdown-policy.js";
-export * from "./documents/index.js";
 export { QaPolicyAdmission } from "./secure-session.js";
+export { QaAccessService } from "./access/service.js";
+export { QaRoleRepository } from "./access/role-repository.js";
+export { QaAgentToolGrants } from "./enforcement/tool-grants.js";
+export { defaultCapabilityConfig, normalizeCapabilityConfig, normalizeUserAccess, resolveCapabilityPolicy, resolveSkillAccess, } from "./access/model.js";
+export { parseQaSkillMetadata, resolveSkillVisibility, } from "./access/skill-metadata.js";
 export { QaPromptNotes, renderUserIdentity, QA_IDENTITY_NOTE, QA_SOURCES_NOTE, } from "./prompt-notes.js";
 export * from "./provenance/index.js";
 export type * from "./types.js";

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

@@ -28,6 +28,8 @@ export declare class QaTools implements QaToolActivation {
     constructor(ctx: Context, options: QaToolsOptions);
     /** Names currently registered on one agent; the admission guard reads this per call. */
     activeToolNames(agent: Agent): readonly string[];
+    /** Shipped scope-local names, including entries not activated on an agent yet. */
+    catalogToolNames(): readonly string[];
     dispose(): void;
     /**
      * The preset gate. An empty `activationPresets` leaves it open, which is only

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

@@ -1,6 +1,7 @@
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaResolvedSessionPolicy } from "./access/service.js";
 import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
 /**
  * The accounts half of admission, resolved per call by the entry (accounts
@@ -32,6 +33,10 @@ export declare class QaPolicyAdmission {
      * it is registered and stops being callable once the agent is disposed.
      */
     private readonly dynamicToolNames;
+    /** Resolve and freeze the session's subrole policy after its agent exists. */
+    private readonly capabilityPolicy?;
+    /** Scope-local catalog entries may be known before they are activated. */
+    private readonly knownDynamicToolNames;
     private readonly appliedPolicies;
     /** Host-trusted principal-scoped plugin tools enabled outside static config. */
     private readonly principalScopedTools;
@@ -49,7 +54,11 @@ export declare class QaPolicyAdmission {
      * skill loaded. Read per execution, so a tool becomes callable exactly when
      * it is registered and stops being callable once the agent is disposed.
      */
-    dynamicToolNames?: (agent: Agent) => readonly string[]);
+    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, 
+    /** Scope-local catalog entries may be known before they are activated. */
+    knownDynamicToolNames?: () => readonly string[]);
     /**
      * Add tools whose own executor resolves the QA principal server-side.
      * Enabling the contributing plugin is the operator decision; model arguments