@yadsh/dsh-qa-surface 0.6.0 → 0.7.0

package/lib/enforcement/tool-grants.js

@@ -0,0 +1,151 @@
+function describe(tools) {
+    return tools.map((tool) => `"${tool}"`).join(", ");
+}
+/**
+ * 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 class QaAgentToolGrants {
+    options;
+    active = new Map();
+    tools;
+    disposeRestriction;
+    constructor(options) {
+        this.options = options;
+        this.tools = new Set(options.baseTools);
+        this.applyRestriction([...this.tools]);
+    }
+    /** Whether the model would see this tool right now. */
+    effectiveTools() {
+        return this.tools;
+    }
+    /** Grants currently held, newest last; one entry per activated skill. */
+    activeGrants() {
+        return [...this.active.values()];
+    }
+    /**
+     * 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, origin) {
+        const descriptor = this.options.descriptors.get(skillName);
+        const requested = [...(descriptor?.requiredTools ?? [])];
+        const candidates = requested.filter((tool) => this.options.grantableTools.includes(tool));
+        const before = [...this.tools];
+        const accepted = [];
+        for (const tool of candidates) {
+            if (this.tools.has(tool)) {
+                accepted.push(tool);
+                continue;
+            }
+            try {
+                this.applyRestriction([...this.tools, tool]);
+                this.tools.add(tool);
+                accepted.push(tool);
+            }
+            catch {
+                // The registry refused the name (unregistered or agent-local), so the
+                // tool stays out of the grant rather than breaking the activation.
+            }
+        }
+        const denied = requested.filter((tool) => !accepted.includes(tool));
+        if (descriptor?.requireAll === true && denied.length > 0) {
+            this.restore(before);
+            const reason = `Skill "${skillName}" cannot be activated because required tool ${describe(denied)} is unavailable for the current role.`;
+            this.commit(skillName, origin, "rejected", requested, [], denied, reason);
+            return { status: "rejected", reason };
+        }
+        const grant = Object.freeze({
+            skillName,
+            origin,
+            requestedTools: Object.freeze(requested),
+            grantedTools: Object.freeze(accepted),
+            deniedTools: Object.freeze(denied),
+            activatedAt: new Date().toISOString(),
+        });
+        this.active.set(skillName, grant);
+        this.options.logger.info("skill-grant.activated", {
+            skill: skillName,
+            origin,
+            granted: accepted,
+            denied,
+        });
+        this.commit(skillName, origin, "activated", requested, accepted, denied);
+        const warning = denied.length === 0
+            ? undefined
+            : [
+                "Skill loaded with limited capabilities.",
+                "",
+                "Unavailable required tools:",
+                ...denied.map((tool) => `- ${tool}`),
+            ].join("\n");
+        return {
+            status: "activated",
+            grant,
+            ...(warning === undefined ? {} : { warning }),
+        };
+    }
+    /** Record an audience refusal; no tool state changes. */
+    deny(skillName, origin, reason) {
+        const descriptor = this.options.descriptors.get(skillName);
+        this.commit(skillName, origin, "denied", descriptor?.requiredTools ?? [], [], descriptor?.requiredTools ?? [], reason);
+    }
+    /** Lift the restriction this instance owns. Safe to call more than once. */
+    dispose() {
+        const dispose = this.disposeRestriction;
+        this.disposeRestriction = undefined;
+        this.active.clear();
+        this.tools.clear();
+        for (const tool of this.options.baseTools)
+            this.tools.add(tool);
+        dispose?.();
+    }
+    /**
+     * 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.
+     */
+    applyRestriction(allow) {
+        const next = this.options.agent.ctx.tools.restrict({ allow: [...allow] });
+        const previous = this.disposeRestriction;
+        this.disposeRestriction = next;
+        previous?.();
+    }
+    restore(before) {
+        this.tools.clear();
+        for (const tool of before)
+            this.tools.add(tool);
+        this.applyRestriction(before);
+    }
+    commit(skillName, origin, outcome, requested, granted, denied, reason) {
+        this.options.record?.(Object.freeze({
+            timestamp: new Date().toISOString(),
+            skillName,
+            origin,
+            outcome,
+            requestedTools: Object.freeze([...requested]),
+            grantedTools: Object.freeze([...granted]),
+            deniedTools: Object.freeze([...denied]),
+            ...(reason === undefined ? {} : { reason }),
+        }));
+    }
+}
+//# sourceMappingURL=tool-grants.js.map

package/lib/enforcement/tool-grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-grants.js","sourceRoot":"","sources":["../../src/enforcement/tool-grants.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -39,11 +39,12 @@ import { WorkspaceId } from "@deepseek-ai/dsh-workspace";
 import { createHostLoggerSink, getPluginLogger, } from "@yadsh/dsh-plugin-log";
 import { ConfigSchema, resolveConfig } from "./config.js";
 import { createQaAccountRemotes } from "./account-remotes.js";
+import { QaAdminService } from "./admin/service.js";
+import { QaQualityStore } from "./admin/quality-store.js";
+import { createSessionLogReader } from "./admin/session-log.js";
 import { createQaPersonalSkillRemotes, QaPersonalSkillsHost, } from "./personal-skills/index.js";
 import { QaApprovalGate } from "./approvals.js";
-import { QaAttestationError } from "./attestation.js";
-import { applyDocumentsEnvOverrides } from "./documents/config.js";
-import { installDocumentSubsystem, } from "./documents/index.js";
+import { QaAttestationError, qaAttestationFailureMessage, } from "./attestation.js";
 import { QaQuestionGate } from "./questions.js";
 import { QaSessionOwnership } from "./session-ownership.js";
 import { entryRedirectRow } from "./entry-redirect.js";
@@ -51,6 +52,7 @@ import { registerQaNavigationRoute } from "./host-route.js";
 import { makeLaunchTokenSource } from "./launch-token.js";
 import { QaIntegrationPrincipalBindings } from "./integration-principals.js";
 import { QaPolicyAdmission } from "./secure-session.js";
+import { QaAccessService } from "./access/service.js";
 import { QaPromptNotes } from "./prompt-notes.js";
 import { QaTools } from "./qa-tools/index.js";
 import { QaProvenanceHost } from "./provenance/host-store.js";
@@ -95,6 +97,29 @@ let QaSurface = (() => {
     let _accountsUpdateStarters_decorators;
     let _describe_decorators;
     let _createSession_decorators;
+    let _accessCurrent_decorators;
+    let _accessSession_decorators;
+    let _accessAdminSnapshot_decorators;
+    let _accessCreateSubrole_decorators;
+    let _accessUpdateSubrole_decorators;
+    let _accessDeleteSubrole_decorators;
+    let _accessUpdateCommon_decorators;
+    let _accessUpdateAssignment_decorators;
+    let _accessUpdateSkillOverride_decorators;
+    let _accessSkillActivations_decorators;
+    let _adminOverview_decorators;
+    let _adminUsers_decorators;
+    let _adminUser_decorators;
+    let _adminUpdateUser_decorators;
+    let _adminConversations_decorators;
+    let _adminConversation_decorators;
+    let _adminFeedback_decorators;
+    let _adminRateMessage_decorators;
+    let _adminReviewQueue_decorators;
+    let _adminQueueConversation_decorators;
+    let _adminSaveReview_decorators;
+    let _adminMetrics_decorators;
+    let _adminAudit_decorators;
     let _secureSession_decorators;
     let _sources_decorators;
     let _pendingApprovals_decorators;
@@ -123,6 +148,29 @@ let QaSurface = (() => {
             _accountsUpdateStarters_decorators = [Remote("accountsUpdateStarters")];
             _describe_decorators = [Remote("describe")];
             _createSession_decorators = [Remote("createSession")];
+            _accessCurrent_decorators = [Remote("accessCurrent")];
+            _accessSession_decorators = [Remote("accessSession")];
+            _accessAdminSnapshot_decorators = [Remote("accessAdminSnapshot")];
+            _accessCreateSubrole_decorators = [Remote("accessCreateSubrole")];
+            _accessUpdateSubrole_decorators = [Remote("accessUpdateSubrole")];
+            _accessDeleteSubrole_decorators = [Remote("accessDeleteSubrole")];
+            _accessUpdateCommon_decorators = [Remote("accessUpdateCommon")];
+            _accessUpdateAssignment_decorators = [Remote("accessUpdateAssignment")];
+            _accessUpdateSkillOverride_decorators = [Remote("accessUpdateSkillOverride")];
+            _accessSkillActivations_decorators = [Remote("accessSkillActivations")];
+            _adminOverview_decorators = [Remote("adminOverview")];
+            _adminUsers_decorators = [Remote("adminUsers")];
+            _adminUser_decorators = [Remote("adminUser")];
+            _adminUpdateUser_decorators = [Remote("adminUpdateUser")];
+            _adminConversations_decorators = [Remote("adminConversations")];
+            _adminConversation_decorators = [Remote("adminConversation")];
+            _adminFeedback_decorators = [Remote("adminFeedback")];
+            _adminRateMessage_decorators = [Remote("adminRateMessage")];
+            _adminReviewQueue_decorators = [Remote("adminReviewQueue")];
+            _adminQueueConversation_decorators = [Remote("adminQueueConversation")];
+            _adminSaveReview_decorators = [Remote("adminSaveReview")];
+            _adminMetrics_decorators = [Remote("adminMetrics")];
+            _adminAudit_decorators = [Remote("adminAudit")];
             _secureSession_decorators = [Remote("secureSession")];
             _sources_decorators = [Remote("sources")];
             _pendingApprovals_decorators = [Remote("pendingApprovals")];
@@ -148,6 +196,29 @@ let QaSurface = (() => {
             __esDecorate(this, null, _accountsUpdateStarters_decorators, { kind: "method", name: "accountsUpdateStarters", static: false, private: false, access: { has: obj => "accountsUpdateStarters" in obj, get: obj => obj.accountsUpdateStarters }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _describe_decorators, { kind: "method", name: "describe", static: false, private: false, access: { has: obj => "describe" in obj, get: obj => obj.describe }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _createSession_decorators, { kind: "method", name: "createSession", static: false, private: false, access: { has: obj => "createSession" in obj, get: obj => obj.createSession }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessCurrent_decorators, { kind: "method", name: "accessCurrent", static: false, private: false, access: { has: obj => "accessCurrent" in obj, get: obj => obj.accessCurrent }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessSession_decorators, { kind: "method", name: "accessSession", static: false, private: false, access: { has: obj => "accessSession" in obj, get: obj => obj.accessSession }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessAdminSnapshot_decorators, { kind: "method", name: "accessAdminSnapshot", static: false, private: false, access: { has: obj => "accessAdminSnapshot" in obj, get: obj => obj.accessAdminSnapshot }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessCreateSubrole_decorators, { kind: "method", name: "accessCreateSubrole", static: false, private: false, access: { has: obj => "accessCreateSubrole" in obj, get: obj => obj.accessCreateSubrole }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessUpdateSubrole_decorators, { kind: "method", name: "accessUpdateSubrole", static: false, private: false, access: { has: obj => "accessUpdateSubrole" in obj, get: obj => obj.accessUpdateSubrole }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessDeleteSubrole_decorators, { kind: "method", name: "accessDeleteSubrole", static: false, private: false, access: { has: obj => "accessDeleteSubrole" in obj, get: obj => obj.accessDeleteSubrole }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessUpdateCommon_decorators, { kind: "method", name: "accessUpdateCommon", static: false, private: false, access: { has: obj => "accessUpdateCommon" in obj, get: obj => obj.accessUpdateCommon }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessUpdateAssignment_decorators, { kind: "method", name: "accessUpdateAssignment", static: false, private: false, access: { has: obj => "accessUpdateAssignment" in obj, get: obj => obj.accessUpdateAssignment }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessUpdateSkillOverride_decorators, { kind: "method", name: "accessUpdateSkillOverride", static: false, private: false, access: { has: obj => "accessUpdateSkillOverride" in obj, get: obj => obj.accessUpdateSkillOverride }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accessSkillActivations_decorators, { kind: "method", name: "accessSkillActivations", static: false, private: false, access: { has: obj => "accessSkillActivations" in obj, get: obj => obj.accessSkillActivations }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminOverview_decorators, { kind: "method", name: "adminOverview", static: false, private: false, access: { has: obj => "adminOverview" in obj, get: obj => obj.adminOverview }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminUsers_decorators, { kind: "method", name: "adminUsers", static: false, private: false, access: { has: obj => "adminUsers" in obj, get: obj => obj.adminUsers }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminUser_decorators, { kind: "method", name: "adminUser", static: false, private: false, access: { has: obj => "adminUser" in obj, get: obj => obj.adminUser }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminUpdateUser_decorators, { kind: "method", name: "adminUpdateUser", static: false, private: false, access: { has: obj => "adminUpdateUser" in obj, get: obj => obj.adminUpdateUser }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminConversations_decorators, { kind: "method", name: "adminConversations", static: false, private: false, access: { has: obj => "adminConversations" in obj, get: obj => obj.adminConversations }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminConversation_decorators, { kind: "method", name: "adminConversation", static: false, private: false, access: { has: obj => "adminConversation" in obj, get: obj => obj.adminConversation }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminFeedback_decorators, { kind: "method", name: "adminFeedback", static: false, private: false, access: { has: obj => "adminFeedback" in obj, get: obj => obj.adminFeedback }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminRateMessage_decorators, { kind: "method", name: "adminRateMessage", static: false, private: false, access: { has: obj => "adminRateMessage" in obj, get: obj => obj.adminRateMessage }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminReviewQueue_decorators, { kind: "method", name: "adminReviewQueue", static: false, private: false, access: { has: obj => "adminReviewQueue" in obj, get: obj => obj.adminReviewQueue }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminQueueConversation_decorators, { kind: "method", name: "adminQueueConversation", static: false, private: false, access: { has: obj => "adminQueueConversation" in obj, get: obj => obj.adminQueueConversation }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminSaveReview_decorators, { kind: "method", name: "adminSaveReview", static: false, private: false, access: { has: obj => "adminSaveReview" in obj, get: obj => obj.adminSaveReview }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminMetrics_decorators, { kind: "method", name: "adminMetrics", static: false, private: false, access: { has: obj => "adminMetrics" in obj, get: obj => obj.adminMetrics }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _adminAudit_decorators, { kind: "method", name: "adminAudit", static: false, private: false, access: { has: obj => "adminAudit" in obj, get: obj => obj.adminAudit }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _secureSession_decorators, { kind: "method", name: "secureSession", static: false, private: false, access: { has: obj => "secureSession" in obj, get: obj => obj.secureSession }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sources_decorators, { kind: "method", name: "sources", static: false, private: false, access: { has: obj => "sources" in obj, get: obj => obj.sources }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _pendingApprovals_decorators, { kind: "method", name: "pendingApprovals", static: false, private: false, access: { has: obj => "pendingApprovals" in obj, get: obj => obj.pendingApprovals }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -178,6 +249,13 @@ let QaSurface = (() => {
         tools;
         /** Account-remote bodies; the wire signatures stay on this class. */
         accountRemotes;
+        /** Roles, assignments, discovery and immutable per-session capability sets. */
+        access;
+        /**
+         * The administrative console: authorization, conversation queries over
+         * stored logs, quality records and their aggregations.
+         */
+        admin;
         /** Personal skills: storage, the DSH provider and the manual-edit watcher. */
         personalSkills;
         /** Personal-skill remote bodies; the wire signatures stay on this class. */
@@ -189,12 +267,10 @@ let QaSurface = (() => {
         disposeRoute;
         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.
          */
-        documents;
-        documentsKey;
+        qualityStore;
         constructor(ctx, entry = {}) {
             super(ctx, "qaSurface", { namespace: "qaSurface" });
             const resolvedEntry = resolveConfig(entry);
@@ -207,11 +283,25 @@ let QaSurface = (() => {
                 getConfig: () => this.getConfig(),
                 logger: this.logger,
             });
+            this.access = new QaAccessService(ctx, {
+                accounts: () => this.accountRemotes.resolve(this.getConfig()),
+                config: () => this.getConfig(),
+                logger: this.logger,
+                dynamicToolNames: () => this.tools?.catalogToolNames() ?? [],
+            });
             this.personalSkills = new QaPersonalSkillsHost({
                 ctx,
                 getConfig: () => this.getConfig(),
                 logger: this.logger,
             });
+            this.admin = new QaAdminService({
+                accounts: () => this.accountRemotes.resolve(this.getConfig()),
+                quality: () => this.quality(),
+                roles: () => this.access.roles,
+                access: () => this.access,
+                sessionLog: createSessionLogReader(ctx),
+                logger: this.logger,
+            });
             this.skillRemotes = createQaPersonalSkillRemotes({
                 getConfig: () => this.getConfig(),
                 logger: this.logger,
@@ -228,9 +318,10 @@ let QaSurface = (() => {
                 },
                 userWorkspace: (userId, registeredWorkspacePath) => existingQaUserWorkspace(registeredWorkspacePath, userId),
             }, 
-            // Dynamically attached QA tools are not operator-configured allow-list
-            // entries, so the execution guard reads them per call instead.
-            (agent) => this.tools?.activeToolNames(agent) ?? []);
+            // Legacy account-free sessions retain the dynamic catalog behavior;
+            // role-managed sessions authorize its known entries through the frozen
+            // capability policy instead.
+            (agent) => this.tools?.activeToolNames(agent) ?? [], (token, sessionId, agent) => this.access.policyForSession(token, sessionId, agent), () => this.tools?.catalogToolNames() ?? []);
             this.provenance = new QaProvenanceHost(ctx, () => this.getConfig(), new FileQaProvenanceSnapshotStore(), (error) => this.logger.error("sources.persistence-failed", {
                 message: error instanceof Error ? error.message : String(error),
             }));
@@ -266,14 +357,7 @@ let QaSurface = (() => {
             ctx.effect(() => () => this.provenance.dispose(), "dsh-qa-surface.provenance");
             ctx.effect(() => () => this.notes.dispose(), "dsh-qa-surface.prompt-notes");
             ctx.effect(() => () => this.personalSkills.dispose(), "dsh-qa-surface.personal-skills");
-            ctx.effect(() => () => {
-                this.documents?.dispose();
-                this.documents = undefined;
-                this.documentsKey = undefined;
-            }, "dsh-qa-surface.documents");
-            // Registered here rather than from the settings callback alone, so a
-            // deployment that never opens the settings page still gets the tools.
-            this.refreshDocuments();
+            this.warnDocumentsMoved();
             // The QA tool catalog is attached per agent, never at boot: nothing here
             // reaches the model until a managed agent loads the activation skill.
             this.tools = new QaTools(ctx, {
@@ -299,12 +383,11 @@ let QaSurface = (() => {
                     onChange: () => {
                         const config = this.getConfig();
                         this.refreshRoute();
-                        this.refreshDocuments();
+                        this.warnDocumentsMoved();
                         this.logger.info("config.updated", {
                             enabled: config.enabled,
                             route: config.route.path,
                             sessionPolicy: config.session.policy,
-                            documents: config.documents.enabled,
                         });
                     },
                     validate: (value) => {
@@ -328,6 +411,11 @@ let QaSurface = (() => {
                 sessionPolicy: resolvedEntry.session.policy,
             });
         }
+        /** The quality store, opening its file the first time anyone needs it. */
+        quality() {
+            this.qualityStore ??= new QaQualityStore();
+            return this.qualityStore;
+        }
         /** Resolve browser authentication to the caller only; never accepts an id. */
         principalForToken(token) {
             const accounts = this.accountRemotes.resolve(this.getConfig());
@@ -417,7 +505,7 @@ let QaSurface = (() => {
          * cwd is `<configured workspace>/.qa-users/<account UUID>` and the child is
          * intentionally not registered or attached as another DSH workspace.
          */
-        async createSession(token) {
+        async createSession(token, subroleId, adminPreview) {
             const config = this.getConfig();
             if (config.session.policy === "fixed") {
                 throw new Error("Fixed QA sessions cannot be created.");
@@ -426,9 +514,12 @@ let QaSurface = (() => {
             const accounts = this.accountRemotes.resolve(config);
             const owner = accounts === undefined
                 ? undefined
-                : this.accountRemotes.run(() => accounts.reserveSession(token, String(id)));
+                : this.accountRemotes.run(() => this.access.reserveSession(token, String(id), subroleId, adminPreview));
             let hostCreated = false;
             try {
+                // Check deployment-only pins before creating a durable Host session.
+                // Full admission below still verifies the composed agent and tool view.
+                this.admission.preflightDeployment();
                 let userCwd;
                 if (config.accounts.perUserWorkspace) {
                     const workspaceId = config.session.workspaceId;
@@ -476,11 +567,108 @@ let QaSurface = (() => {
                 }
                 this.logger.error("session.create-rejected", {
                     sessionId: String(id),
+                    reason: error instanceof QaAttestationError ? error.reason : undefined,
                     error: error instanceof Error ? error.message : String(error),
                 });
-                throw new Error("Unable to create a QA session.", { cause: error });
+                throw new Error(qaAttestationFailureMessage("Unable to create a QA session.", error), { cause: error });
+            }
+        }
+        /** The selector model for the signed-in user; admin grants are irrelevant. */
+        accessCurrent(token) {
+            return this.accountRemotes.run(() => this.access.current(token));
+        }
+        /** The immutable role pinned to an existing session. */
+        accessSession(token, sessionId) {
+            return this.accountRemotes.run(() => this.access.session(token, sessionId), sessionId);
+        }
+        /** Complete administrator projection; authorization is checked before discovery. */
+        async accessAdminSnapshot(token) {
+            try {
+                return await this.access.adminSnapshot(token);
+            }
+            catch (error) {
+                return this.accountRemotes.run(() => {
+                    throw error;
+                });
             }
         }
+        accessCreateSubrole(token, input) {
+            return this.accountRemotes.run(() => this.access.createSubrole(token, input));
+        }
+        accessUpdateSubrole(token, id, input) {
+            return this.accountRemotes.run(() => this.access.updateSubrole(token, id, input));
+        }
+        accessDeleteSubrole(token, id, replacementId) {
+            return this.accountRemotes.run(() => {
+                this.access.deleteSubrole(token, id, replacementId);
+                return { deleted: true };
+            });
+        }
+        accessUpdateCommon(token, input) {
+            return this.accountRemotes.run(() => this.access.updateCommon(token, input));
+        }
+        accessUpdateAssignment(token, userId, input) {
+            return this.accountRemotes.run(() => this.access.updateAssignment(token, userId, input));
+        }
+        /** Layer one administrator assignment over what a SKILL.md declares. */
+        accessUpdateSkillOverride(token, input) {
+            return this.accountRemotes.run(() => this.access.updateSkillOverride(token, input));
+        }
+        /** What each skill activation actually granted in this session. */
+        accessSkillActivations(token, sessionId) {
+            return this.accountRemotes.run(() => this.access.skillActivations(token, sessionId), sessionId);
+        }
+        // ---------------------------------------------------------------------------
+        // Administrative console. Every method names its permission inside the
+        // service; the wire carries a token and never an identity.
+        // ---------------------------------------------------------------------------
+        /** Counters, attention lines and the newest quality signals. */
+        adminOverview(token) {
+            return this.accountRemotes.runAsync(() => this.admin.overview(token));
+        }
+        adminUsers(token, query, cursor, limit) {
+            return this.accountRemotes.runAsync(() => this.admin.users(token, query, cursor ?? undefined, limit ?? undefined));
+        }
+        adminUser(token, userId) {
+            return this.accountRemotes.runAsync(() => this.admin.user(token, userId));
+        }
+        /** Authorization role, status and subrole assignment of one account. */
+        adminUpdateUser(token, userId, update) {
+            return this.accountRemotes.runAsync(() => this.admin.updateUser(token, userId, update));
+        }
+        adminConversations(token, query, cursor, limit) {
+            return this.accountRemotes.runAsync(() => this.admin.conversations(token, query, cursor ?? undefined, limit ?? undefined));
+        }
+        /** One conversation with its messages, tool calls and review state. */
+        adminConversation(token, conversationId) {
+            return this.accountRemotes.runAsync(() => this.admin.conversation(token, conversationId));
+        }
+        adminFeedback(token, query, cursor, limit) {
+            return this.accountRemotes.runAsync(() => this.admin.feedback(token, query, cursor ?? undefined, limit ?? undefined));
+        }
+        /**
+         * 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, conversationId, messageId, input) {
+            return this.accountRemotes.run(() => this.admin.rateMessage(token, conversationId, messageId, input));
+        }
+        adminReviewQueue(token, cursor, limit) {
+            return this.accountRemotes.runAsync(() => this.admin.reviewQueue(token, cursor ?? undefined, limit ?? undefined));
+        }
+        /** Park a conversation for review without rating it. */
+        adminQueueConversation(token, conversationId, messageId) {
+            return this.accountRemotes.run(() => this.admin.queueConversation(token, conversationId, messageId ?? undefined));
+        }
+        adminSaveReview(token, input) {
+            return this.accountRemotes.run(() => this.admin.saveReview(token, input));
+        }
+        adminMetrics(token) {
+            return this.accountRemotes.runAsync(() => this.admin.metrics(token));
+        }
+        adminAudit(token, query, cursor, limit) {
+            return this.accountRemotes.runAsync(() => this.admin.audit(token, query, cursor ?? undefined, limit ?? undefined));
+        }
         /** Pin and attest the effective policy. The browser supplies identity only. */
         async secureSession(token, sessionId) {
             try {
@@ -648,27 +836,21 @@ let QaSurface = (() => {
             this.routeKey = key;
         }
         /**
-         * 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.
          */
-        refreshDocuments() {
-            const config = this.getConfig();
-            const enabled = config.enabled && config.documents.enabled;
-            const key = enabled ? JSON.stringify(config.documents) : undefined;
-            if (key === this.documentsKey)
+        warnDocumentsMoved() {
+            // The section is no longer part of this plugin's schema, so it is read off
+            // the raw entry: unknown keys survive schema parsing on purpose.
+            const legacy = this.source()
+                .documents;
+            if (legacy === undefined || Object.keys(legacy).length === 0)
                 return;
-            this.documents?.dispose();
-            this.documents = undefined;
-            this.documentsKey = key;
-            if (key === undefined)
-                return;
-            this.documents = installDocumentSubsystem(this.ctx, {
-                config: applyDocumentsEnvOverrides(this.source().documents ?? {}, process.env),
-                logger: this.logger,
-                register: (definition) => this.ctx.tools.register(definition),
+            this.logger.warn("documents.moved", {
+                plugin: "@yadsh/dsh-documents",
+                message: "the documents section moved to the @yadsh/dsh-documents plugin; the copy under qa-surface is ignored",
             });
         }
     };
@@ -681,8 +863,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 default QaSurface;