@yadsh/dsh-qa-surface 0.16.0 → 0.18.0

package/lib/index.js

@@ -33,12 +33,14 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     done = true;
 };
 import { randomUUID } from "node:crypto";
+import { readSourceImage as readSourceImagePreview } from "./provenance/source-image.js";
 import path from "node:path";
 import { defaultAccountsFilePath } from "./accounts/store.js";
 import { QaChatSharingStore } from "./chat-sharing/store.js";
 import { QaChatTransport } from "./chat-sharing/transport.js";
 import { QaChatTurnGuard } from "./chat-sharing/turn-guard.js";
 import { installQaNativeFence } from "./chat-sharing/native-fence.js";
+import { QaIntegrationQuestionPolicy } from "./integration/question-policy.js";
 import { qaChatPublishedFile, qaChatAttachmentPath, } from "./chat-sharing/resources.js";
 import { installQaChatUploads } from "./chat-sharing/uploads.js";
 import { forkQaSession } from "./session-fork-host.js";
@@ -56,11 +58,19 @@ import { QaApprovalGate } from "./approvals.js";
 import { QaAttestationError, qaAttestationFailureMessage, } from "./attestation.js";
 import { QaFileDeleteGate } from "./qa-tools/file-delete-gate.js";
 import { QaQuestionGate } from "./questions.js";
+import { QaFormStore } from "./forms/store.js";
+import { QaFormService } from "./forms/service.js";
+import { QaFormGate } from "./forms/gate.js";
+import { QaFormAttachmentAdapter, } from "./forms/attachments.js";
+import { formFailure, QaFormError } from "./forms/errors.js";
 import { QaSessionOwnership } from "./session-ownership.js";
+import { QaLlmIdentity } from "./llm-identity.js";
 import { registerTurnFailureLog } from "./turn-failure-log.js";
 import { entryRedirectRow } from "./entry-redirect.js";
 import { qaKioskDeployment } from "./ui-mode.js";
 import { registerQaNavigationRoute } from "./host-route.js";
+import { QaOidcService, oidcRefusal } from "./oidc/service.js";
+import { registerQaOidcRoute } from "./oidc/http.js";
 import { makeLaunchTokenSource } from "./launch-token.js";
 import { QaIntegrationPrincipalBindings } from "./integration-principals.js";
 import { registerQaIntegrationRoutes } from "./integration/http.js";
@@ -136,6 +146,9 @@ let QaSurface = (() => {
     let _instanceExtraInitializers = [];
     let _accountsRegister_decorators;
     let _accountsLogin_decorators;
+    let _accountsOidcStart_decorators;
+    let _accountsOidcComplete_decorators;
+    let _accountsOidcLogout_decorators;
     let _accountsChangePassword_decorators;
     let _accountsRequestPasswordReset_decorators;
     let _accountsWhoami_decorators;
@@ -148,6 +161,7 @@ let QaSurface = (() => {
     let _accountsListServiceTokens_decorators;
     let _accountsCreateServiceToken_decorators;
     let _accountsRevokeServiceToken_decorators;
+    let _accountsSetServiceTokenClarifications_decorators;
     let _describe_decorators;
     let _queueStatus_decorators;
     let _createSession_decorators;
@@ -215,9 +229,16 @@ let QaSurface = (() => {
     let _pendingApprovals_decorators;
     let _answerApproval_decorators;
     let _pendingQuestions_decorators;
+    let _listForms_decorators;
+    let _getForm_decorators;
+    let _mutateForm_decorators;
+    let _validateFormStep_decorators;
+    let _formCapabilities_decorators;
+    let _readFormAttachment_decorators;
     let _answerQuestion_decorators;
     let _cancelQuestion_decorators;
     let _readSourceFile_decorators;
+    let _readSourceImage_decorators;
     let _listWorkspaceFiles_decorators;
     let _readWorkspaceFile_decorators;
     let _readWorkspaceFileChunk_decorators;
@@ -238,6 +259,9 @@ let QaSurface = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _accountsRegister_decorators = [Remote("accountsRegister")];
             _accountsLogin_decorators = [Remote("accountsLogin")];
+            _accountsOidcStart_decorators = [Remote("accountsOidcStart")];
+            _accountsOidcComplete_decorators = [Remote("accountsOidcComplete")];
+            _accountsOidcLogout_decorators = [Remote("accountsOidcLogout")];
             _accountsChangePassword_decorators = [Remote("accountsChangePassword")];
             _accountsRequestPasswordReset_decorators = [Remote("accountsRequestPasswordReset")];
             _accountsWhoami_decorators = [Remote("accountsWhoami")];
@@ -250,6 +274,7 @@ let QaSurface = (() => {
             _accountsListServiceTokens_decorators = [Remote("accountsListServiceTokens")];
             _accountsCreateServiceToken_decorators = [Remote("accountsCreateServiceToken")];
             _accountsRevokeServiceToken_decorators = [Remote("accountsRevokeServiceToken")];
+            _accountsSetServiceTokenClarifications_decorators = [Remote("accountsSetServiceTokenClarifications")];
             _describe_decorators = [Remote("describe")];
             _queueStatus_decorators = [Remote("queueStatus")];
             _createSession_decorators = [Remote("createSession")];
@@ -317,9 +342,16 @@ let QaSurface = (() => {
             _pendingApprovals_decorators = [Remote("pendingApprovals")];
             _answerApproval_decorators = [Remote("answerApproval")];
             _pendingQuestions_decorators = [Remote("pendingQuestions")];
+            _listForms_decorators = [Remote("listForms")];
+            _getForm_decorators = [Remote("getForm")];
+            _mutateForm_decorators = [Remote("mutateForm")];
+            _validateFormStep_decorators = [Remote("validateFormStep")];
+            _formCapabilities_decorators = [Remote("formCapabilities")];
+            _readFormAttachment_decorators = [Remote("readFormAttachment")];
             _answerQuestion_decorators = [Remote("answerQuestion")];
             _cancelQuestion_decorators = [Remote("cancelQuestion")];
             _readSourceFile_decorators = [Remote("readSourceFile")];
+            _readSourceImage_decorators = [Remote("readSourceImage")];
             _listWorkspaceFiles_decorators = [Remote("listWorkspaceFiles")];
             _readWorkspaceFile_decorators = [Remote("readWorkspaceFile")];
             _readWorkspaceFileChunk_decorators = [Remote("readWorkspaceFileChunk")];
@@ -337,6 +369,9 @@ let QaSurface = (() => {
             _slashExecute_decorators = [Remote("slashExecute")];
             __esDecorate(this, null, _accountsRegister_decorators, { kind: "method", name: "accountsRegister", static: false, private: false, access: { has: obj => "accountsRegister" in obj, get: obj => obj.accountsRegister }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _accountsLogin_decorators, { kind: "method", name: "accountsLogin", static: false, private: false, access: { has: obj => "accountsLogin" in obj, get: obj => obj.accountsLogin }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accountsOidcStart_decorators, { kind: "method", name: "accountsOidcStart", static: false, private: false, access: { has: obj => "accountsOidcStart" in obj, get: obj => obj.accountsOidcStart }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accountsOidcComplete_decorators, { kind: "method", name: "accountsOidcComplete", static: false, private: false, access: { has: obj => "accountsOidcComplete" in obj, get: obj => obj.accountsOidcComplete }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accountsOidcLogout_decorators, { kind: "method", name: "accountsOidcLogout", static: false, private: false, access: { has: obj => "accountsOidcLogout" in obj, get: obj => obj.accountsOidcLogout }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _accountsChangePassword_decorators, { kind: "method", name: "accountsChangePassword", static: false, private: false, access: { has: obj => "accountsChangePassword" in obj, get: obj => obj.accountsChangePassword }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _accountsRequestPasswordReset_decorators, { kind: "method", name: "accountsRequestPasswordReset", static: false, private: false, access: { has: obj => "accountsRequestPasswordReset" in obj, get: obj => obj.accountsRequestPasswordReset }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _accountsWhoami_decorators, { kind: "method", name: "accountsWhoami", static: false, private: false, access: { has: obj => "accountsWhoami" in obj, get: obj => obj.accountsWhoami }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -349,6 +384,7 @@ let QaSurface = (() => {
             __esDecorate(this, null, _accountsListServiceTokens_decorators, { kind: "method", name: "accountsListServiceTokens", static: false, private: false, access: { has: obj => "accountsListServiceTokens" in obj, get: obj => obj.accountsListServiceTokens }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _accountsCreateServiceToken_decorators, { kind: "method", name: "accountsCreateServiceToken", static: false, private: false, access: { has: obj => "accountsCreateServiceToken" in obj, get: obj => obj.accountsCreateServiceToken }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _accountsRevokeServiceToken_decorators, { kind: "method", name: "accountsRevokeServiceToken", static: false, private: false, access: { has: obj => "accountsRevokeServiceToken" in obj, get: obj => obj.accountsRevokeServiceToken }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _accountsSetServiceTokenClarifications_decorators, { kind: "method", name: "accountsSetServiceTokenClarifications", static: false, private: false, access: { has: obj => "accountsSetServiceTokenClarifications" in obj, get: obj => obj.accountsSetServiceTokenClarifications }, 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, _queueStatus_decorators, { kind: "method", name: "queueStatus", static: false, private: false, access: { has: obj => "queueStatus" in obj, get: obj => obj.queueStatus }, 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);
@@ -416,9 +452,16 @@ let QaSurface = (() => {
             __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);
             __esDecorate(this, null, _answerApproval_decorators, { kind: "method", name: "answerApproval", static: false, private: false, access: { has: obj => "answerApproval" in obj, get: obj => obj.answerApproval }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _pendingQuestions_decorators, { kind: "method", name: "pendingQuestions", static: false, private: false, access: { has: obj => "pendingQuestions" in obj, get: obj => obj.pendingQuestions }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listForms_decorators, { kind: "method", name: "listForms", static: false, private: false, access: { has: obj => "listForms" in obj, get: obj => obj.listForms }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getForm_decorators, { kind: "method", name: "getForm", static: false, private: false, access: { has: obj => "getForm" in obj, get: obj => obj.getForm }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mutateForm_decorators, { kind: "method", name: "mutateForm", static: false, private: false, access: { has: obj => "mutateForm" in obj, get: obj => obj.mutateForm }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _validateFormStep_decorators, { kind: "method", name: "validateFormStep", static: false, private: false, access: { has: obj => "validateFormStep" in obj, get: obj => obj.validateFormStep }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _formCapabilities_decorators, { kind: "method", name: "formCapabilities", static: false, private: false, access: { has: obj => "formCapabilities" in obj, get: obj => obj.formCapabilities }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _readFormAttachment_decorators, { kind: "method", name: "readFormAttachment", static: false, private: false, access: { has: obj => "readFormAttachment" in obj, get: obj => obj.readFormAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _answerQuestion_decorators, { kind: "method", name: "answerQuestion", static: false, private: false, access: { has: obj => "answerQuestion" in obj, get: obj => obj.answerQuestion }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _cancelQuestion_decorators, { kind: "method", name: "cancelQuestion", static: false, private: false, access: { has: obj => "cancelQuestion" in obj, get: obj => obj.cancelQuestion }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _readSourceFile_decorators, { kind: "method", name: "readSourceFile", static: false, private: false, access: { has: obj => "readSourceFile" in obj, get: obj => obj.readSourceFile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _readSourceImage_decorators, { kind: "method", name: "readSourceImage", static: false, private: false, access: { has: obj => "readSourceImage" in obj, get: obj => obj.readSourceImage }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _listWorkspaceFiles_decorators, { kind: "method", name: "listWorkspaceFiles", static: false, private: false, access: { has: obj => "listWorkspaceFiles" in obj, get: obj => obj.listWorkspaceFiles }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _readWorkspaceFile_decorators, { kind: "method", name: "readWorkspaceFile", static: false, private: false, access: { has: obj => "readWorkspaceFile" in obj, get: obj => obj.readWorkspaceFile }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _readWorkspaceFileChunk_decorators, { kind: "method", name: "readWorkspaceFileChunk", static: false, private: false, access: { has: obj => "readWorkspaceFileChunk" in obj, get: obj => obj.readWorkspaceFileChunk }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -444,6 +487,13 @@ let QaSurface = (() => {
         approvals;
         fileDeleteGate;
         userQuestions;
+        formService;
+        formGate;
+        formAttachments;
+        forms() {
+            return (this.formService ??= new QaFormService(new QaFormStore(path.join(path.dirname(defaultAccountsFilePath()), "qa-forms.db")), () => this.getConfig().forms, (session) => this.accountRemotes.resolve(this.getConfig())?.ownerIdOf(session) ??
+                session));
+        }
         provenance;
         notes;
         /** Assigned after the admission gate; that gate only reads it per execution. */
@@ -472,6 +522,12 @@ let QaSurface = (() => {
         integrationPrincipals = new QaIntegrationPrincipalBindings();
         webServer;
         disposeRoute;
+        oidc = new QaOidcService({
+            config: () => this.getConfig(),
+            accounts: () => this.accountRemotes.resolve(this.getConfig()),
+        });
+        disposeOidcRoute;
+        oidcRouteKey;
         routeKey;
         /**
          * The HTTP API an external application asks questions through. Constructed
@@ -509,6 +565,7 @@ let QaSurface = (() => {
                 pluginId: "dsh-qa-surface",
                 consoleSink: createHostLoggerSink(ctx.logger),
             });
+            this.formAttachments = new QaFormAttachmentAdapter(() => this.forms(), () => ctx.get("attachments"));
             this.accountRemotes = createQaAccountRemotes({
                 getConfig: () => this.getConfig(),
                 logger: this.logger,
@@ -623,7 +680,7 @@ let QaSurface = (() => {
             }, "dsh-qa-surface.chat-sharing");
             ctx.inject(["typertGateway", "connection"], () => {
                 const dispose = installQaNativeFence(ctx, () => this.getConfig().accounts.enabled);
-                const disposeUploads = installQaChatUploads(ctx, () => this.sharing(), (token, id) => this.secureSession(token, id));
+                const disposeUploads = installQaChatUploads(ctx, () => this.sharing(), (token, id) => this.secureSession(token, id), this.formAttachments);
                 return async () => {
                     dispose();
                     await disposeUploads();
@@ -654,8 +711,28 @@ let QaSurface = (() => {
             // operator's answer while they are interactive. The question seam shares
             // the ownership map: one chat, one surface answering it.
             const ownership = new QaSessionOwnership((sessionId) => this.admission.knowsSession(sessionId));
+            ownership.install(ctx);
+            new QaLlmIdentity(ctx, {
+                rootOf: (sessionId) => ownership.rootOf(sessionId),
+                accounts: () => this.accountRemotes.resolve(this.getConfig()),
+            });
             this.approvals = new QaApprovalGate(ctx, () => this.getConfig().interaction.approvals === "interactive", ownership, this.logger);
-            this.userQuestions = new QaQuestionGate(ctx, () => this.getConfig().interaction.questions === "interactive", ownership, this.logger);
+            const integrationQuestionPolicy = new QaIntegrationQuestionPolicy(ctx, () => this.accountRemotes.resolve(this.getConfig()), (id) => ownership.rootOf(id));
+            ctx.effect(() => () => integrationQuestionPolicy.dispose(), "qa-surface: integration question policy");
+            this.userQuestions = new QaQuestionGate(ctx, () => this.getConfig().interaction.questions === "interactive", ownership, this.logger, (agent) => integrationQuestionPolicy.allowed(agent) &&
+                !this.formGate?.hasSession(ownership.rootOf(String(agent.session.id)) ?? ""));
+            this.formGate = new QaFormGate(() => this.forms(), (id) => ownership.rootOf(id), (id) => this.userQuestions.list(id).length > 0 ||
+                this.approvals.list(id).length > 0, (exec) => this.getConfig().forms.enabled &&
+                exec.agent !== undefined &&
+                integrationQuestionPolicy.allowed(exec.agent) &&
+                this.admission.knowsSession(String(exec.agent.session.id)), () => this.getConfig().accounts.enabled &&
+                this.ctx.get("fileUploads") !== undefined &&
+                this.formAttachments.available());
+            this.formGate.install(ctx);
+            ctx.effect(() => () => {
+                this.formGate.dispose();
+                this.formService?.store.close();
+            }, "dsh-qa-surface.forms");
             // The destructive tool of the QA catalog composes the same approval flow
             // around itself: registered without `prepend`, it sits inside the approval
             // gate and answers `ask` for every file_delete call of an attested chat,
@@ -706,6 +783,9 @@ let QaSurface = (() => {
             // 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, {
+                forms: this.formGate,
+                formsEnabled: () => this.getConfig().forms.enabled,
+                formProjection: (submission) => this.formAttachments.readable(submission),
                 logger: this.logger,
                 dynamicActivation: this.getConfig().tools.dynamicActivation,
                 activationSkill: this.getConfig().tools.activationSkill,
@@ -718,6 +798,12 @@ let QaSurface = (() => {
                 docsDefaultVersion: () => docsDefaultVersionOf(this.getConfig().tools),
             });
             ctx.effect(() => () => this.tools.dispose(), "dsh-qa-surface.qa-tools");
+            const listenVolatile = ctx.on.bind(ctx);
+            ctx.effect(() => listenVolatile("loader/volatile-update", () => {
+                this.tools.refreshForms();
+                if (!this.getConfig().forms.enabled)
+                    this.formGate.cancelAll();
+            }), "dsh-qa-surface.form-policy");
             // The root index gains one head script: non-loopback hostnames continue
             // into /qa, the loopback operator keeps the full harness UI. Not in the
             // kiosk composition: there the index itself is served under /qa, so the
@@ -744,6 +830,7 @@ let QaSurface = (() => {
                 const config = this.getConfig();
                 this.refreshRoute();
                 this.refreshIntegrationRoutes();
+                this.refreshOidcRoute();
                 this.warnDocumentsMoved();
                 this.warnLegacySlashDefaults();
                 this.logger.info("config.updated", {
@@ -756,11 +843,16 @@ let QaSurface = (() => {
                 this.webServer = webContext.webServer;
                 this.refreshRoute();
                 this.refreshIntegrationRoutes();
+                this.refreshOidcRoute();
                 webContext.effect(() => () => {
                     this.disposeRoute?.();
                     this.disposeRoute = undefined;
                     this.routeKey = undefined;
                     this.disposeIntegrationRoutes?.();
+                    this.disposeOidcRoute?.();
+                    this.disposeOidcRoute = undefined;
+                    this.oidcRouteKey = undefined;
+                    this.oidc.clear();
                     this.disposeIntegrationRoutes = undefined;
                     this.integrationRouteKey = undefined;
                     this.webServer = undefined;
@@ -811,6 +903,10 @@ let QaSurface = (() => {
          * cannot be opened must not fail the page that triggered it.
          */
         dropVanishedChats(sessionIds) {
+            for (const id of sessionIds) {
+                this.formGate?.cancel(id);
+                this.formService?.store.cancelSession(id);
+            }
             try {
                 const rows = this.quality().dropConversations(sessionIds);
                 this.logger.info("quality.vanished-conversations-dropped", {
@@ -911,6 +1007,17 @@ let QaSurface = (() => {
         accountsLogin(email, password) {
             return this.accountRemotes.login(email, password);
         }
+        accountsOidcStart() {
+            if (!this.disposeOidcRoute)
+                return Promise.reject(oidcRefusal());
+            return this.oidc.start();
+        }
+        accountsOidcComplete(handoff, completionKey) {
+            return this.oidc.complete(handoff, completionKey);
+        }
+        accountsOidcLogout(token) {
+            return this.oidc.logout(token);
+        }
         /** Identity probe; safe to call with an empty or expired token. */
         accountsChangePassword(token, currentPassword, nextPassword) {
             return this.accountRemotes.changePassword(token, currentPassword, nextPassword);
@@ -998,6 +1105,9 @@ let QaSurface = (() => {
         accountsRevokeServiceToken(token, tokenId) {
             return this.accountRemotes.revokeServiceToken(token, tokenId);
         }
+        accountsSetServiceTokenClarifications(token, tokenId, allowed) {
+            return this.accountRemotes.setServiceTokenClarifications(token, tokenId, allowed);
+        }
         /**
          * Serve the effective QA configuration to the browser. The DSH gateway pins
          * settings RPCs to loopback, so a browser served over the LAN always sees
@@ -1387,7 +1497,9 @@ let QaSurface = (() => {
         }
         async chatAudit(token, sessionId, full) {
             this.requireChatOwner(token, sessionId);
-            await this.secureSession(token, sessionId);
+            // Sidebar summaries read stored audit metadata; they do not need an agent.
+            if (full)
+                await this.secureSession(token, sessionId);
             this.requireChatOwner(token, sessionId);
             const audit = this.ctx.get("sessionAudit");
             if (audit === undefined)
@@ -1504,6 +1616,115 @@ let QaSurface = (() => {
                 return [];
             return this.userQuestions.list(sessionId);
         }
+        /** Forms stay owner-scoped; UUIDs and a browser-supplied session never grant access. */
+        async admitForm(token, sessionId) {
+            try {
+                this.requireChatOwner(token, sessionId);
+                await this.secureSession(token, sessionId);
+                this.requireChatOwner(token, sessionId);
+            }
+            catch {
+                throw new QaFormError("ACCESS_DENIED", "Form access is unavailable.");
+            }
+        }
+        async listForms(token, sessionId) {
+            try {
+                await this.admitForm(token, sessionId);
+                if (!this.getConfig().forms.enabled)
+                    return { ok: true, value: [] };
+                this.formGate.touch(sessionId);
+                const service = this.forms();
+                return {
+                    ok: true,
+                    value: service.store
+                        .list(sessionId)
+                        .map((r) => service.view(r, this.formGate.waiting(r.id))),
+                };
+            }
+            catch (error) {
+                return formFailure(error);
+            }
+        }
+        async getForm(token, sessionId, formId) {
+            try {
+                await this.admitForm(token, sessionId);
+                const s = this.forms();
+                return {
+                    ok: true,
+                    value: s.view(s.get(sessionId, formId), this.formGate.waiting(formId)),
+                };
+            }
+            catch (error) {
+                return formFailure(error);
+            }
+        }
+        async mutateForm(token, sessionId, command) {
+            try {
+                await this.admitForm(token, sessionId);
+                const s = this.forms(), r = s.command(sessionId, command);
+                this.logger.info("form.mutated", {
+                    sessionId,
+                    formId: r.id,
+                    action: command.action,
+                    revision: r.revision,
+                    status: r.status,
+                });
+                this.formGate.notify(r, command.action === "pause");
+                return { ok: true, value: s.view(r, this.formGate.waiting(r.id)) };
+            }
+            catch (error) {
+                return formFailure(error);
+            }
+        }
+        async validateFormStep(token, sessionId, formId, stepId, revision) {
+            try {
+                await this.admitForm(token, sessionId);
+                this.forms().step(sessionId, formId, stepId, revision);
+                return { ok: true, value: null };
+            }
+            catch (error) {
+                return formFailure(error);
+            }
+        }
+        async formCapabilities() {
+            return {
+                enabled: this.getConfig().forms.enabled,
+                schemaVersion: 1,
+                upload: this.getConfig().accounts.enabled &&
+                    this.ctx.get("fileUploads") !== undefined &&
+                    this.formAttachments.available(),
+            };
+        }
+        async readFormAttachment(token, sessionId, formId, resourceId) {
+            try {
+                await this.admitForm(token, sessionId);
+                const s = this.forms(), r = s.get(sessionId, formId);
+                const file = Object.values(r.attachments)
+                    .flat()
+                    .find((f) => f.resource_id === resourceId);
+                if (!file)
+                    return {
+                        ok: false,
+                        error: {
+                            code: "ACCESS_DENIED",
+                            message: "File access is unavailable.",
+                        },
+                    };
+                const data = s.store.resource(formId, resourceId);
+                this.requireChatOwner(token, sessionId);
+                return {
+                    ok: true,
+                    value: {
+                        name: file.name,
+                        media_type: file.media_type,
+                        data: Buffer.from(data).toString("base64"),
+                    },
+                };
+            }
+            catch (error) {
+                return formFailure(error);
+            }
+        }
         /**
          * Apply the operator's answers to one parked question request. Every question
          * of the request must be present in `answers`; one the browser omits reads as
@@ -1531,7 +1752,7 @@ let QaSurface = (() => {
          * read — the normal case for a deployment whose docs and code live beside
          * the per-account scratch directory — could never be opened in the panel.
          */
-        async readSourceFile(token, sessionId, sourcePath) {
+        async readSourceFile(token, sessionId, sourcePath, selection) {
             const finish = await this.admitChatRead(token, sessionId, sourcePath);
             const config = this.getConfig();
             if (!config.sources.filePreview.enabled) {
@@ -1551,6 +1772,7 @@ let QaSurface = (() => {
                     ...(attachmentRoot === undefined ? {} : { attachmentRoot }),
                     maxBytes: config.sources.filePreview.maxBytes,
                     maxMarkdownRenderBytes: config.sources.filePreview.maxMarkdownRenderBytes,
+                    renderFrontmatter: config.sources.filePreview.renderFrontmatter,
                 }).catch(async (error) => {
                     // Only a format refusal follows successful evidence and root checks.
                     if (!(error instanceof QaSourcePreviewError) ||
@@ -1564,6 +1786,7 @@ let QaSurface = (() => {
                         ...(attachmentRoot === undefined ? {} : { attachmentRoot }),
                         documents: () => this.ctx.get("documents"),
                         maxBytes: config.sources.filePreview.maxBytes,
+                        ...(selection === undefined ? {} : { selection }),
                     });
                     return {
                         path: sourcePath,
@@ -1586,6 +1809,31 @@ let QaSurface = (() => {
                 throw sourcePreviewRefusal(error instanceof QaSourcePreviewError ? error.reason : "unavailable");
             }
         }
+        /** Load one relative raster illustration of an attested Markdown source. */
+        async readSourceImage(token, sessionId, sourcePath, imagePath) {
+            const finish = await this.admitChatRead(token, sessionId, sourcePath);
+            const config = this.getConfig();
+            const cwd = this.ctx.agents.get(SessionId(sessionId))?.session.header.cwd;
+            if (!config.sources.filePreview.enabled || cwd === undefined)
+                throw sourcePreviewRefusal("unavailable");
+            const attachmentRoot = this.admission.attachmentRoot();
+            try {
+                const result = await readSourceImagePreview({
+                    sourcePath,
+                    cwd,
+                    isEvidence: (canonicalPath) => this.provenance.sourceAllowed(sessionId, canonicalPath),
+                    sharedReadOnlyRoots: config.lockdown.sharedReadOnlyRoots,
+                    ...(attachmentRoot === undefined ? {} : { attachmentRoot }),
+                    maxBytes: config.sources.filePreview.maxBytes,
+                    maxMarkdownRenderBytes: config.sources.filePreview.maxMarkdownRenderBytes,
+                }, imagePath);
+                finish();
+                return result;
+            }
+            catch (error) {
+                throw sourcePreviewRefusal(error instanceof QaSourcePreviewError ? error.reason : "unavailable");
+            }
+        }
         /**
          * List one directory of the chat's own workspace for the files panel.
          *
@@ -1711,7 +1959,7 @@ let QaSurface = (() => {
          * produced PDF is read back here and travels as base64, so the audience never
          * reaches an unfenced byte route.
          */
-        async previewWorkspaceDocument(token, sessionId, path) {
+        async previewWorkspaceDocument(token, sessionId, path, selection) {
             const finish = await this.admitChatRead(token, sessionId, path);
             const { config, cwd } = await this.browseContext(sessionId);
             const attachmentRoot = this.admission.attachmentRoot();
@@ -1724,6 +1972,7 @@ let QaSurface = (() => {
                     documents: () => this.ctx.get("documents"),
                     sessionId,
                     maxBytes: config.sources.filePreview.maxBytes,
+                    ...(selection === undefined ? {} : { selection }),
                 });
                 finish();
                 return value;
@@ -1854,6 +2103,28 @@ let QaSurface = (() => {
                 });
             }
         }
+        refreshOidcRoute() {
+            const config = this.getConfig();
+            const key = config.enabled && config.accounts.enabled && config.accounts.oidc.enabled
+                ? JSON.stringify([config.accounts.oidc, config.route.path])
+                : undefined;
+            if (key === this.oidcRouteKey)
+                return;
+            this.disposeOidcRoute?.();
+            this.disposeOidcRoute = undefined;
+            this.oidcRouteKey = undefined;
+            this.oidc.clear();
+            if (!key || !this.webServer)
+                return;
+            try {
+                this.disposeOidcRoute = registerQaOidcRoute(this.webServer, config, this.oidc);
+                this.oidcRouteKey = key;
+                this.logger.info("oidc.route-registered", {});
+            }
+            catch {
+                this.logger.error("oidc.route-unavailable", {});
+            }
+        }
         refreshRoute() {
             const config = this.getConfig();
             // Kiosk: the harness route policy owns the QA paths and serves the