@yadsh/dsh-qa-surface 0.16.0 → 0.18.0

package/lib/types/forms/types.d.ts

@@ -0,0 +1,215 @@
+/** Browser-safe wire contract; storage and tool waiting have independent lifetimes. */
+export interface QaFormPolicy {
+    enabled: boolean;
+    maxSteps: number;
+    maxItemsPerForm: number;
+    maxOptionsPerItem: number;
+    maxSchemaBytes: number;
+    maxTextLength: number;
+    maxTotalAnswerBytes: number;
+    maxFilesPerItem: number;
+    maxFileSizeBytes: number;
+    maxTotalFileBytesPerForm: number;
+    maxConcurrentUploadsPerSession: number;
+    uploadIntentTtlSeconds: number;
+    allowedExtensions: readonly string[];
+}
+export interface QaFormOption {
+    value: string;
+    label: string;
+    description?: string | undefined;
+    recommended?: boolean | undefined;
+}
+export type QaFormAnswerSpec = {
+    type: "text" | "textarea";
+    required: boolean;
+    placeholder?: string | undefined;
+    min_length?: number | undefined;
+    max_length?: number | undefined;
+} | {
+    type: "single_select" | "multi_select";
+    required: boolean;
+    options: QaFormOption[];
+    allow_other?: boolean | undefined;
+    min_selected?: number | undefined;
+    max_selected?: number | undefined;
+};
+export type QaFormFilesSpec = {
+    requirement: "none";
+} | {
+    requirement: "required";
+    min_count: number;
+    max_count: number;
+    accept: string[];
+    max_file_size_bytes: number;
+} | {
+    requirement: "optional";
+    max_count: number;
+    accept: string[];
+    max_file_size_bytes: number;
+};
+export interface QaFormItem {
+    id: string;
+    title: string;
+    description?: string | undefined;
+    answer?: QaFormAnswerSpec | undefined;
+    files: QaFormFilesSpec;
+}
+export interface QaFormStep {
+    id: string;
+    title: string;
+    description?: string | undefined;
+    items: QaFormItem[];
+}
+export interface QaFormSchema {
+    schema_version: 1;
+    title: string;
+    description?: string | undefined;
+    submit_label?: string | undefined;
+    steps: QaFormStep[];
+}
+export type QaFormAnswer = {
+    type: "text" | "textarea";
+    text: string;
+} | {
+    type: "single_select" | "multi_select";
+    selected: string[];
+    other_text?: string | undefined;
+};
+export interface QaFormAttachment {
+    attachment_id: string;
+    version: number;
+    name: string;
+    size_bytes: number;
+    media_type: string;
+    sha256: string;
+    resource_id: string;
+}
+export interface QaFormUpload {
+    id: string;
+    item_id: string;
+    name: string;
+    size_bytes: number;
+    state: "pending" | "uploading" | "failed" | "ready" | "cancelled";
+    expires_at: number;
+    target?: {
+        attachment_id: string;
+        version: number;
+    } | undefined;
+    result?: QaFormAttachment;
+    error?: string;
+}
+export interface QaFormFieldError {
+    step_id: string;
+    item_id: string;
+    component: "answer" | "files";
+    code: string;
+    message: string;
+}
+export interface QaFormSubmission {
+    status: "submitted";
+    form_id: string;
+    submission_id: string;
+    schema_version: 1;
+    schema_hash: string;
+    form_revision: number;
+    submitted_at: string;
+    items: {
+        step_id: string;
+        item_id: string;
+        answer: QaFormAnswer | null;
+        files: QaFormAttachment[];
+    }[];
+    empty_optional_item_ids: string[];
+}
+export interface QaFormRecord {
+    storage_version: 1;
+    id: string;
+    session_id: string;
+    creator_id: string;
+    request_key: string;
+    schema: QaFormSchema;
+    schema_hash: string;
+    status: "draft" | "submitted" | "cancelled" | "expired";
+    revision: number;
+    created_at: string;
+    answers: Record<string, QaFormAnswer | null>;
+    attachments: Record<string, QaFormAttachment[]>;
+    uploads: QaFormUpload[];
+    step: number;
+    submission?: QaFormSubmission;
+}
+export type QaFormView = QaFormRecord & {
+    waiting: boolean;
+    field_errors: QaFormFieldError[];
+};
+export interface QaFormMutation {
+    form_id: string;
+    expected_revision: number;
+    mutation_id: string;
+}
+export type QaFormCommand = (QaFormMutation & {
+    action: "save";
+    answers: Record<string, QaFormAnswer | null>;
+    step: number;
+}) | (QaFormMutation & {
+    action: "submit" | "pause";
+}) | (QaFormMutation & {
+    action: "begin_upload";
+    item_id: string;
+    name: string;
+    size_bytes: number;
+    target?: {
+        attachment_id: string;
+        version: number;
+    } | undefined;
+}) | (QaFormMutation & {
+    action: "cancel_upload";
+    upload_id: string;
+}) | (QaFormMutation & {
+    action: "remove";
+    item_id: string;
+    attachment_id: string;
+    version: number;
+});
+export type QaFormResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        form_revision?: number;
+        field_errors?: QaFormFieldError[];
+    };
+};
+/**
+ * The store surface the service programs against.
+ *
+ * The service must never reach into a concrete storage backend: the shipped
+ * store is sqlite (durable), and the client component tests mount an in-memory
+ * implementation, which a browser test environment could never load through
+ * the sqlite bridge.
+ */
+export interface QaFormStoreApi {
+    list(session: string): QaFormRecord[];
+    create(session: string, key: string, schema: QaFormRecord["schema"], creator?: string): QaFormRecord;
+    get(session: string, id: string): QaFormRecord;
+    editableOrSubmitted(record: QaFormRecord): void;
+    mutate(session: string, id: string, revision: number, mutationId: string, input: unknown, work: (r: QaFormRecord) => void): QaFormRecord;
+    update(session: string, id: string, work: (r: QaFormRecord) => void): QaFormRecord;
+    resource(formId: string, id: string): Uint8Array;
+    saveResource(formId: string, id: string, data: Uint8Array): void;
+    storedBytes(session: string): number;
+    identityReservedBytes(creator: string): number;
+    cancelSession(session: string): void;
+    /**
+     * Submit retries are idempotent: when this mutation identity was already
+     * applied, return its recorded result and refuse a reused identity that
+     * carries different data. `null` means the identity is unused.
+     */
+    replayedMutation(formId: string, mutationId: string, input: unknown): QaFormRecord | null;
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/forms/validation.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { QaFormAnswer, QaFormAnswerSpec, QaFormFieldError, QaFormPolicy, QaFormRecord } from "./types.js";
+export declare const formAnswerParser: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodEnum<{
+        text: "text";
+        textarea: "textarea";
+    }>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodEnum<{
+        multi_select: "multi_select";
+        single_select: "single_select";
+    }>;
+    selected: z.ZodArray<z.ZodString>;
+    other_text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+/** Requiredness is checked at navigation/submit; invalid supplied values fail even if optional. */
+export declare function normalizeFormAnswer(spec: QaFormAnswerSpec | undefined, raw: unknown, policy: Readonly<QaFormPolicy>, requireComplete?: boolean): QaFormAnswer | null;
+export declare function validateForm(record: QaFormRecord, policy: Readonly<QaFormPolicy>, stepId?: string): QaFormFieldError[];
+//# sourceMappingURL=validation.d.ts.map

package/lib/types/index.d.ts

@@ -3,9 +3,10 @@ import type { SessionPageRequest, SessionFollowRequest, SessionPromptRequest, Se
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import type { Context } from "@deepseek-ai/cordis";
 import type { QaSurfaceConfigRefs } from "./config.js";
+import type { QaFormCommand, QaFormResult, QaFormView } from "./forms/types.js";
 import type { QaAccountNotificationsInput } from "./types.js";
 import type { QaTurnSources } from "./provenance/types.js";
-import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaDocumentPreview, QaDocumentWorkflowStatus, QaIssuedServiceToken, QaLockdownProof, QaOwnershipEntry, QaPasswordResetRequest, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaQueueStatus, QaServiceTokenCreateInput, QaServiceTokenSummary, ResolvedQaSurfaceConfig, QaAdminSkillScope, QaAdminSkillsView, QaExpertMemoryDraft, QaExpertMemoryPage, QaExpertMemoryRecord, QaExpertMemoryScope, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaWorkspaceFile, QaWorkspaceFileChunk, QaWorkspaceListing, QaPrincipal, QaAccessAdminSnapshot, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaCapabilitySelection, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaCurrentAccess, QaFeedbackHarvestEntry, QaFeedbackHarvestResult, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaModelCatalogEntry, QaModelPair, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSessionAccess, QaSlashCatalog, QaSlashExecution, QaSlashSubmitAttachment, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, QaUserQuery } from "./types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaDocumentPreview, QaSpreadsheetPreviewSelection, QaDocumentWorkflowStatus, QaIssuedServiceToken, QaLockdownProof, QaOwnershipEntry, QaPasswordResetRequest, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaQueueStatus, QaServiceTokenCreateInput, QaServiceTokenSummary, ResolvedQaSurfaceConfig, QaAdminSkillScope, QaAdminSkillsView, QaExpertMemoryDraft, QaExpertMemoryPage, QaExpertMemoryRecord, QaExpertMemoryScope, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaWorkspaceFile, QaWorkspaceFileChunk, QaWorkspaceListing, QaPrincipal, QaAccessAdminSnapshot, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaCapabilitySelection, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaCurrentAccess, QaFeedbackHarvestEntry, QaFeedbackHarvestResult, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaModelCatalogEntry, QaModelPair, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSessionAccess, QaSlashCatalog, QaSlashExecution, QaSlashSubmitAttachment, 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";
@@ -26,6 +27,10 @@ export declare class QaSurface extends TypertRemoteService {
     private readonly approvals;
     private readonly fileDeleteGate;
     private readonly userQuestions;
+    private formService?;
+    private readonly formGate;
+    private readonly formAttachments;
+    private forms;
     private readonly provenance;
     private readonly notes;
     /** Assigned after the admission gate; that gate only reads it per execution. */
@@ -54,6 +59,9 @@ export declare class QaSurface extends TypertRemoteService {
     private readonly integrationPrincipals;
     private webServer;
     private disposeRoute;
+    private readonly oidc;
+    private disposeOidcRoute;
+    private oidcRouteKey;
     private routeKey;
     /**
      * The HTTP API an external application asks questions through. Constructed
@@ -142,6 +150,9 @@ export declare class QaSurface extends TypertRemoteService {
      */
     accountsRegister(email: string, password: string): QaAccountSession;
     accountsLogin(email: string, password: string): QaAccountSession;
+    accountsOidcStart(): Promise<import("./types.js").QaOidcStart>;
+    accountsOidcComplete(handoff: string, completionKey: string): QaAccountSession;
+    accountsOidcLogout(token: string): Promise<string | null>;
     /** Identity probe; safe to call with an empty or expired token. */
     accountsChangePassword(token: string, currentPassword: string, nextPassword: string): QaAccountSession;
     /**
@@ -214,6 +225,9 @@ export declare class QaSurface extends TypertRemoteService {
     accountsRevokeServiceToken(token: string, tokenId: string): {
         readonly revoked: boolean;
     };
+    accountsSetServiceTokenClarifications(token: string, tokenId: string, allowed: boolean): {
+        readonly updated: boolean;
+    };
     /**
      * 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
@@ -388,6 +402,22 @@ export declare class QaSurface extends TypertRemoteService {
      * deployment with unsupported questions answers with an empty list.
      */
     pendingQuestions(token: string, sessionId: string): Promise<readonly QaPendingQuestion[]>;
+    /** Forms stay owner-scoped; UUIDs and a browser-supplied session never grant access. */
+    private admitForm;
+    listForms(token: string, sessionId: string): Promise<QaFormResult<QaFormView[]>>;
+    getForm(token: string, sessionId: string, formId: string): Promise<QaFormResult<QaFormView>>;
+    mutateForm(token: string, sessionId: string, command: QaFormCommand): Promise<QaFormResult<QaFormView>>;
+    validateFormStep(token: string, sessionId: string, formId: string, stepId: string, revision: number): Promise<QaFormResult<null>>;
+    formCapabilities(): Promise<{
+        enabled: boolean;
+        schemaVersion: number;
+        upload: boolean;
+    }>;
+    readFormAttachment(token: string, sessionId: string, formId: string, resourceId: string): Promise<QaFormResult<{
+        name: string;
+        media_type: string;
+        data: string;
+    }>>;
     /**
      * 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
@@ -405,7 +435,9 @@ export declare class QaSurface extends TypertRemoteService {
      * 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.
      */
-    readSourceFile(token: string, sessionId: string, sourcePath: string): Promise<QaSourceFilePreview>;
+    readSourceFile(token: string, sessionId: string, sourcePath: string, selection?: QaSpreadsheetPreviewSelection): Promise<QaSourceFilePreview>;
+    /** Load one relative raster illustration of an attested Markdown source. */
+    readSourceImage(token: string, sessionId: string, sourcePath: string, imagePath: string): Promise<string>;
     /**
      * List one directory of the chat's own workspace for the files panel.
      *
@@ -439,7 +471,7 @@ export declare class QaSurface extends TypertRemoteService {
      * produced PDF is read back here and travels as base64, so the audience never
      * reaches an unfenced byte route.
      */
-    previewWorkspaceDocument(token: string, sessionId: string, path: string): Promise<QaDocumentPreview>;
+    previewWorkspaceDocument(token: string, sessionId: string, path: string, selection?: QaSpreadsheetPreviewSelection): Promise<QaDocumentPreview>;
     /**
      * Shared admission facts of both browse methods: the preview switch is what
      * opens the panel's file reading at all, and the chat's cwd is the tree that
@@ -506,6 +538,7 @@ export declare class QaSurface extends TypertRemoteService {
      * immediately rather than at the next restart.
      */
     private refreshIntegrationRoutes;
+    private refreshOidcRoute;
     private refreshRoute;
     /**
      * A deployment that set `lockdown.allowSlashCommands: true` before this

package/lib/types/integration/contract.d.ts

@@ -166,6 +166,7 @@ export interface QaIntegrationRunner {
         /** The chat to continue, or null for a new conversation. */
         readonly chatId: string | null;
         readonly message: string;
+        readonly allowClarifications?: boolean;
         readonly attachments: readonly QaIntegrationAttachment[];
         readonly ticketKey: string | null;
         /** Ends the wait: the caller's own lifetime merged with the deployment's budget. */

package/lib/types/integration/question-policy.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { QaAccounts } from "../accounts/store.js";
+export declare const QA_INTEGRATION_NO_CLARIFICATIONS = "Clarifying questions are disabled for this integration turn. Do not call ask_user_question or ask follow-up questions in your answer. Answer from available evidence, label assumptions and missing facts, and state what cannot be determined when evidence is insufficient. Do not invent facts or bypass permission approvals.";
+/** A queued request's durable policy follows its turn and its delegated agents. */
+export declare class QaIntegrationQuestionPolicy {
+    private readonly ctx;
+    private readonly accounts;
+    private readonly qaRoot;
+    private readonly turns;
+    private readonly notes;
+    private readonly disposers;
+    constructor(ctx: Context, accounts: () => QaAccounts | undefined, qaRoot?: (id: string) => string | undefined);
+    allowed(agent: Agent): boolean;
+    private root;
+    /** Recover after a plugin reload from consumed messages, never queued future input. */
+    private recover;
+    dispose(): void;
+}
+//# sourceMappingURL=question-policy.d.ts.map

package/lib/types/integration/service.d.ts

@@ -31,6 +31,7 @@ export declare const QA_INTEGRATION_MAX_CITATIONS = 5;
 export declare function sourceCitations(sources: readonly QaSourceReference[]): readonly string[];
 /** Who a presented credential turned out to be. */
 export interface QaIntegrationIdentity {
+    readonly allowClarifications: boolean;
     readonly tokenId: string;
     readonly userId: string;
     readonly scopes: readonly QaServiceTokenScope[];

package/lib/types/llm-identity.d.ts

@@ -0,0 +1,20 @@
+import { Service, type Context } from "@deepseek-ai/cordis";
+import type { QaAccounts } from "./accounts/store.js";
+interface IdentityAccounts {
+    ownerIdOf: QaAccounts["ownerIdOf"];
+    accountById: QaAccounts["accountById"];
+}
+export interface QaLlmIdentityOptions {
+    /** Resolves only roots attested by this QA deployment and their live children. */
+    rootOf(sessionId: string): string | undefined;
+    accounts(): IdentityAccounts | undefined;
+}
+/** Runtime-only identity seam; it grants no account or tool access. */
+export declare class QaLlmIdentity extends Service {
+    private readonly options;
+    constructor(ctx: Context, options: QaLlmIdentityOptions);
+    /** Stable pseudonym of the chat's active owner, never the browser viewing it. */
+    forSession(sessionId: string): string | undefined;
+}
+export {};
+//# sourceMappingURL=llm-identity.d.ts.map

package/lib/types/markdown-frontmatter.d.ts

@@ -0,0 +1,10 @@
+import type { QaSourceMetadata } from "./provenance/types.js";
+export interface MarkdownFrontmatter {
+    readonly body: string;
+    /** Physical lines removed, including both fences. */
+    readonly offset: number;
+    readonly fields: QaSourceMetadata;
+}
+/** Only a complete, bounded YAML mapping at the start earns a metadata card. */
+export declare function readFrontmatter(text: string): MarkdownFrontmatter | undefined;
+//# sourceMappingURL=markdown-frontmatter.d.ts.map

package/lib/types/markdown-images.d.ts

@@ -0,0 +1,3 @@
+/** Exact image destinations from the same grammar the source preview renders. */
+export declare function markdownImageTargets(text: string): ReadonlySet<string>;
+//# sourceMappingURL=markdown-images.d.ts.map

package/lib/types/oidc/http.d.ts

@@ -0,0 +1,5 @@
+import type { WebServer } from "@deepseek-ai/dsh-host-webserver";
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaOidcService } from "./service.js";
+export declare function registerQaOidcRoute(webServer: Pick<WebServer, "register">, config: ResolvedQaSurfaceConfig, service: QaOidcService): () => void;
+//# sourceMappingURL=http.d.ts.map

package/lib/types/oidc/service.d.ts

@@ -0,0 +1,30 @@
+import * as oidc from "openid-client";
+import type { QaAccounts } from "../accounts/store.js";
+import type { QaAccountSession, QaOidcStart, ResolvedQaSurfaceConfig } from "../types.js";
+/** A coarse refusal never carries provider responses, codes or tokens. */
+export declare function oidcRefusal(): Error;
+/** Authorization Code + PKCE with a browser-bound, single-use QA handoff. */
+export declare class QaOidcService {
+    private readonly options;
+    private generation;
+    private key;
+    private discovery;
+    private readonly transactions;
+    private readonly handoffs;
+    private attempts;
+    constructor(options: {
+        config: () => ResolvedQaSurfaceConfig;
+        accounts: () => QaAccounts | undefined;
+        discover?: typeof oidc.discovery;
+    });
+    private sync;
+    clear(): void;
+    private prune;
+    private client;
+    start(): Promise<QaOidcStart>;
+    /** Callback is reconstructed from configured origin, never Host/Forwarded headers. */
+    callback(requestUrl: string): Promise<string>;
+    complete(handoff: string, completionKey: string): QaAccountSession;
+    logout(token: string): Promise<string | null>;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/oidc.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oidc.js.map

package/lib/types/oidc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.js","sourceRoot":"","sources":["../../src/types/oidc.ts"],"names":[],"mappings":""}

package/lib/types/prompt-notes.d.ts

@@ -41,7 +41,7 @@ export declare const QA_IDENTITY_NOTE_TEMPLATE = "{identity}\n\n{instructions}";
 export declare const QA_SOURCES_NOTE_TEMPLATE = "Source provenance is collected automatically from your tool calls; the QA surface lists what it collected beside the answer. Do not append a manual Sources/\u0418\u0441\u0442\u043E\u0447\u043D\u0438\u043A\u0438 bibliography of your own.";
 export declare const QA_SOURCES_FALLBACK_TEMPLATE = "A delegated run whose provider cannot expose tool events must call {reportTool} before finishing.";
 export declare const QA_DELEGATION_NOTE_TEMPLATE = "When you start a background subagent, give the delegation a short vivid name in its description field: two or three words in the user's language that say what the run is for (\u00AB\u0421\u0432\u0435\u0440\u043A\u0430 \u043E\u0442\u0447\u0451\u0442\u043E\u0432\u00BB, \"Log triage\"). The QA surface shows that description as the subagent's display name in the operator's panel and completion notices.";
-export declare const QA_DOCUMENTS_NOTE_TEMPLATE = "A document a chat user attached is a path on disk, not text: read it with the deployment's document pipeline \u2014 `document_inspect` says what a DOCX or PDF is, `document_to_markdown` extracts its text, `document_from_url` stores the text of an attachment that only exists behind a URL. The plain file reader refuses those formats as binary, so that refusal is expected and is not a hint to go looking for the file somewhere else. When the pipeline itself refuses a path, report the refusal and the path it named instead of trying another reader.";
+export declare const QA_DOCUMENTS_NOTE_TEMPLATE = "A document a chat user attached is a path on disk, not text: read it with the deployment's document pipeline \u2014 `document_inspect` says what a DOCX or PDF is, `document_to_markdown` extracts its text, `document_from_url` stores the text of an attachment that only exists behind a URL. For XLSX, CSV, TSV, ODS or FODS, `spreadsheet_inspect` lists all sheets and detects text delimiter/encoding, `spreadsheet_read` reads pages, and `spreadsheet_create` creates a file in the selected format. CSV/TSV have one Data sheet with string fields; reuse detected delimiter and encoding when paging. XLSX/ODS/FODS support multiple sheets. Inspect all sheet names before selecting data; formula values are saved caches, not recalculated results. The plain file reader refuses those formats as binary, so that refusal is expected and is not a hint to go looking for the file somewhere else. When the pipeline itself refuses a path, report the refusal and the path it named instead of trying another reader.";
 export declare const QA_SOURCE_PRIORITY_NOTE_TEMPLATE = "Answer from the source that owns the question: read what the conversation and its attachments already carry, then search the product documentation and ask the domain expert, and only then look in memory. Recalled memory is background from earlier sessions \u2014 a miss there is not evidence that no source exists, and it is not where a document, a page or a product fact should be looked up.";
 export interface QaIdentityRenderInput {
     /** The owner's account address; the one fact accounts always provide. */

package/lib/types/provenance/document-preview.d.ts

@@ -1,5 +1,5 @@
 import type { DocumentsFace } from "@yadsh/dsh-documents";
-import type { QaDocumentPreview } from "../types.js";
+import type { QaDocumentPreview, QaSpreadsheetPreviewSelection } from "../types.js";
 import { type QaAllowedFileRequest } from "./file-preview.js";
 /** Look up the document subsystem a sibling Host plugin published. */
 export type DocumentsLookup = () => DocumentsFace | undefined;
@@ -9,6 +9,7 @@ export interface QaDocumentPreviewRequest extends QaAllowedFileRequest {
     readonly sessionId: string;
     /** Bytes of the rendered PDF the panel accepts before it gives up. */
     readonly maxBytes: number;
+    readonly selection?: QaSpreadsheetPreviewSelection;
 }
 /**
  * Render one Word document as a PDF for the files panel.
@@ -24,7 +25,7 @@ export interface QaDocumentPreviewRequest extends QaAllowedFileRequest {
  * an uploaded Word file lives in the attachment store, and a pipeline that is
  * not told about that root refuses the file this check just accepted.
  */
-export declare function previewConvertibleDocument({ documents, sessionId, maxBytes, ...file }: QaDocumentPreviewRequest): Promise<QaDocumentPreview>;
+export declare function previewConvertibleDocument({ documents, sessionId, maxBytes, selection, ...file }: QaDocumentPreviewRequest): Promise<QaDocumentPreview>;
 /** Native PDF or pipeline preview, after the caller has verified chat evidence. */
 export declare function previewSourceDocument(request: QaDocumentPreviewRequest): Promise<QaDocumentPreview>;
 //# sourceMappingURL=document-preview.d.ts.map

package/lib/types/provenance/file-preview.d.ts

@@ -40,6 +40,7 @@ export interface QaSourceFilePreviewRequest {
     readonly attachmentRoot?: string;
     readonly maxBytes: number;
     readonly maxMarkdownRenderBytes: number;
+    readonly renderFrontmatter?: boolean;
 }
 /** A file request the panel may make: the chat's own tree or a shared root. */
 export interface QaAllowedFileRequest {
@@ -77,7 +78,7 @@ export declare function resolveAllowedFile({ filePath, cwd, sharedReadOnlyRoots,
  * same way before it is matched, or a file inside the chat's own workspace is
  * refused as foreign evidence.
  */
-export declare function readSourceFilePreview({ sourcePath, cwd, isEvidence, sharedReadOnlyRoots, attachmentRoot, maxBytes, maxMarkdownRenderBytes, }: QaSourceFilePreviewRequest): Promise<QaSourceFilePreview>;
+export declare function readSourceFilePreview({ sourcePath, cwd, isEvidence, sharedReadOnlyRoots, attachmentRoot, maxBytes, maxMarkdownRenderBytes, renderFrontmatter, }: QaSourceFilePreviewRequest): Promise<QaSourceFilePreview>;
 /** One directory request from the files panel. */
 export interface QaWorkspaceListRequest {
     /** The directory to list, absolute or relative to the chat cwd. Empty = root. */

package/lib/types/provenance/source-content.d.ts

@@ -0,0 +1,19 @@
+/** Text retained from a single addressed tool result, never from model prose. */
+export declare const MAX_SOURCE_CONTENT = 32000;
+type RecordValue = Record<string, unknown>;
+export declare function retainedSourceContent(value: string | undefined, partial?: boolean): {
+    content?: undefined;
+    contentTruncated?: undefined;
+} | {
+    content: string;
+    contentTruncated: boolean;
+};
+export declare function structuredSourceContent(item: RecordValue): {
+    content?: undefined;
+    contentTruncated?: undefined;
+} | {
+    content: string;
+    contentTruncated: boolean;
+};
+export {};
+//# sourceMappingURL=source-content.d.ts.map

package/lib/types/provenance/source-image.d.ts

@@ -0,0 +1,4 @@
+import { type QaSourceFilePreviewRequest } from "./file-preview.js";
+/** The image must be named by an attested Markdown file and stay inside allowed roots. */
+export declare function readSourceImage(request: QaSourceFilePreviewRequest, imagePath: string): Promise<string>;
+//# sourceMappingURL=source-image.d.ts.map

package/lib/types/provenance/spreadsheet-preview.d.ts

@@ -0,0 +1,5 @@
+import type { QaDocumentPreviewRequest } from "./document-preview.js";
+import type { QaSpreadsheetPreview } from "../types.js";
+/** Reuse the agent's bounded parser and the panel's canonical root fence. */
+export declare function previewSpreadsheetDocument(request: QaDocumentPreviewRequest): Promise<QaSpreadsheetPreview>;
+//# sourceMappingURL=spreadsheet-preview.d.ts.map

package/lib/types/provenance/types.d.ts

@@ -33,6 +33,9 @@ export interface QaSourceReference {
     readonly uri?: string;
     readonly path?: string;
     readonly snippet?: string;
+    /** Bounded text actually returned for this source by a retrieval tool. */
+    readonly content?: string;
+    readonly contentTruncated?: boolean;
     readonly locations: readonly QaSourceLocation[];
     readonly evidence: QaSourceEvidence;
     readonly origins: readonly QaSourceOrigin[];

package/lib/types/qa-tools/activation-manager.d.ts

@@ -19,7 +19,12 @@ export interface QaToolActivationManagerOptions {
 export declare class QaToolActivationManager implements QaToolActivation {
     private readonly options;
     private readonly states;
+    private readonly activeAgents;
+    private catalog;
     constructor(options: QaToolActivationManagerOptions);
+    /** Reconcile feature switches only for scopes which already earned activation. */
+    replaceCatalog(catalog: readonly QaToolDescriptor[]): void;
+    disposeAll(): void;
     /**
      * Register the whole catalog on one agent, all or nothing.
      *

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

@@ -1,5 +1,6 @@
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { QaToolDescriptor } from "./types.js";
+import type { QaFormGate } from "../forms/gate.js";
 /**
  * Deterministic catalog identity. The durable activation marker is derived from
  * the session log rather than stored, so this version is not compared against a
@@ -8,9 +9,11 @@ import type { QaToolDescriptor } from "./types.js";
  *
  * Bump it whenever the catalog's tool set or their schemas change.
  */
-export declare const QA_TOOL_CATALOG_VERSION = "3";
+export declare const QA_TOOL_CATALOG_VERSION = "4";
 /** What the catalog's definitions read, beyond the execution record. */
 export interface QaToolsSelfcheckDeps {
+    readonly forms?: QaFormGate;
+    readonly formProjection?: (submission: import("../forms/types.js").QaFormSubmission) => Promise<unknown>;
     readonly catalogVersion: string;
     readonly activationMode: string;
     /** Names the catalog contributes, in catalog order. */

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

@@ -3,6 +3,9 @@ import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaToolActivation } from "./types.js";
 export interface QaToolsOptions {
+    readonly forms?: import("../forms/gate.js").QaFormGate;
+    readonly formsEnabled?: () => boolean;
+    readonly formProjection?: (submission: import("../forms/types.js").QaFormSubmission) => Promise<unknown>;
     readonly logger: PluginLogger;
     readonly dynamicActivation: boolean;
     readonly activationSkill: string;
@@ -31,12 +34,13 @@ export declare class QaTools implements QaToolActivation {
     private readonly manager;
     private readonly detector;
     private readonly lifecycle;
-    private readonly catalogTools;
+    private catalogTools;
     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[];
+    refreshForms(): void;
     dispose(): void;
     /**
      * The preset gate. An empty `activationPresets` leaves it open, which is only

package/lib/types/qa-tools/request-user-form.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type { QaFormGate } from "../forms/gate.js";
+/** Build only; the QA activation manager owns registration and role admission. */
+export declare function createRequestUserFormTool(gate: QaFormGate, project?: (submission: import("../forms/types.js").QaFormSubmission) => Promise<unknown>): ToolDefinition;
+//# sourceMappingURL=request-user-form.d.ts.map

package/lib/types/questions.d.ts

@@ -62,9 +62,10 @@ export declare class QaQuestionGate {
     private readonly interactive;
     private readonly ownership;
     private readonly logger;
+    private readonly questionsAllowed;
     private readonly pending;
     private readonly disposers;
-    constructor(ctx: Context, interactive: () => boolean, ownership: QaSessionOwnership, logger: PluginLogger);
+    constructor(ctx: Context, interactive: () => boolean, ownership: QaSessionOwnership, logger: PluginLogger, questionsAllowed?: (agent: Agent) => boolean);
     /** Claim question requests for the chats this deployment answers. */
     install(): void;
     /** Questions of one chat, oldest first: what the QA view renders. */