@yadsh/dsh-qa-surface 0.2.0 → 0.4.0

package/lib/types/index.d.ts

@@ -1,9 +1,11 @@
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import type { Context } from "@deepseek-ai/cordis";
-import type { QaLockdownProof, QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
+import type { QaTurnSources } from "./provenance/types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountUserPublic, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSourceFilePreview, QaWhoamiResult } from "./types.js";
 export declare const name = "qa-surface";
 export declare const inject: string[];
-export declare const QA_SURFACE_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+import { QA_SURFACE_SETTINGS_NAMESPACE } from "./shared/settings.js";
+export { QA_SURFACE_SETTINGS_NAMESPACE };
 export declare const Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
 declare module "@deepseek-ai/cordis" {
     interface Context {
@@ -17,11 +19,46 @@ export declare class QaSurface extends TypertRemoteService {
     private source;
     private readonly logger;
     private readonly admission;
+    private readonly provenance;
+    private readonly notes;
+    /** Account-remote bodies; the wire signatures stay on this class. */
+    private readonly accountRemotes;
+    private readonly launchToken;
     private webServer;
     private disposeRoute;
     private routeKey;
     constructor(ctx: Context, entry?: QaSurfaceConfig);
     getConfig(): ResolvedQaSurfaceConfig;
+    /**
+     * Self-service signup; the first account ever created becomes admin. The
+     * display name derives from the email: the generated client enforces exact
+     * wire arity, so an optional name parameter would still be required.
+     */
+    accountsRegister(email: string, password: string): QaAccountSession;
+    accountsLogin(email: string, password: string): QaAccountSession;
+    /** Identity probe; safe to call with an empty or expired token. */
+    accountsWhoami(token: string): QaWhoamiResult;
+    /** Migrate a browser's local chat index into server-side ownership. */
+    accountsClaimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
+    /** The token user's owned session ids; the sidebar list authority. */
+    accountsOwnedSessions(token: string): {
+        readonly ids: readonly string[];
+    };
+    /**
+     * Every chat-ownership entry with owner display names; the cross-user view
+     * admin browsers group the sidebar by. Ordinary accounts are refused with
+     * the dedicated reason, anonymous ones with auth-required.
+     */
+    accountsListOwnership(token: string): {
+        readonly entries: readonly QaOwnershipEntry[];
+    };
+    /**
+     * Replace the caller's own self-declared profile. The token is the only
+     * identity the wire carries: a browser can never name a profile but its own,
+     * and the deployment's declared fields and length limits are enforced in the
+     * store before anything is written.
+     */
+    accountsUpdateProfile(token: string, input: QaAccountProfileInput): QaAccountUserPublic;
     /**
      * 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
@@ -30,16 +67,30 @@ export declare class QaSurface extends TypertRemoteService {
      * boundary stays in {@link secureSession}.
      */
     describe(): ResolvedQaSurfaceConfig;
+    /**
+     * Create a QA session from Host-owned inputs. With account workspaces on,
+     * cwd is `<configured workspace>/.qa-users/<account UUID>` and the child is
+     * intentionally not registered or attached as another DSH workspace.
+     */
+    createSession(token: string): Promise<string>;
     /** Pin and attest the effective policy. The browser supplies identity only. */
-    secureSession(sessionId: string): QaLockdownProof;
+    secureSession(token: string, sessionId: string): QaLockdownProof;
+    /** Return canonical Host snapshots; replay is rebuilt from qa/sources events. */
+    sources(token: string, sessionId: string): readonly QaTurnSources[];
+    /** Narrow read-only preview capability for files already present as sources. */
+    readSourceFile(token: string, sessionId: string, sourcePath: string): Promise<QaSourceFilePreview>;
     private refreshRoute;
 }
 export { ConfigSchema, DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath, resolveConfig, } from "./config.js";
 export { QaAttestationError } from "./attestation.js";
 export type { QaAttestationReason } from "./attestation.js";
+export { QaAccounts, QaAccountsError } from "./accounts/store.js";
+export { entryRedirectRow, entryRedirectScript } from "./entry-redirect.js";
 export { registerQaNavigationRoute } from "./host-route.js";
 export { qaToolDenial, qaToolPolicyPlan } from "./lockdown-policy.js";
 export { QaPolicyAdmission } from "./secure-session.js";
+export { QaPromptNotes, renderUserIdentity, QA_IDENTITY_NOTE, QA_SOURCES_NOTE, } from "./prompt-notes.js";
+export * from "./provenance/index.js";
 export type * from "./types.js";
 export default QaSurface;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/launch-token.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Plugin-side launch-token bridge (the pattern proven by dsh-auth-gate): the
+ * 0.1.x host exposes `connection.authenticatedUrl(baseUrl)` whose `?token=`
+ * parameter carries the per-process launch token. The `/qa` route handler
+ * uses it to send cookie-less browsers through the one-time host-cookie
+ * exchange themselves, so the transparent entry works without the qa-deploy
+ * proxy. The host/scheme of the resolved URL are dropped — the redirect is
+ * relative, so the browser stays on the origin it actually used.
+ */
+export type LaunchTokenSource = () => string | undefined;
+interface AuthenticatedUrlFace {
+    authenticatedUrl?(baseUrl: string): string;
+}
+/**
+ * Resolve the launch token once per process (it is stable for the process
+ * lifetime); a missing connection service or an unusable answer warns once
+ * and permanently disables the bridge instead of retrying per request.
+ */
+export declare function makeLaunchTokenSource(getConnection: () => AuthenticatedUrlFace | undefined, warn: (message: string) => void): LaunchTokenSource;
+export {};
+//# sourceMappingURL=launch-token.d.ts.map

package/lib/types/profile.d.ts

@@ -0,0 +1,76 @@
+import type { QaAccountIdentityField, QaAccountProfile } from "./types.js";
+/**
+ * Profile shape, limits, and the normalization both halves of the plugin
+ * agree on. Deliberately free of Node built-ins: the configuration resolver
+ * and the browser-side form import these same limits, and a Host-only import
+ * here would drag the accounts store into the client bundle.
+ */
+/** Longest accepted full name. */
+export declare const QA_PROFILE_MAX_FULL_NAME = 200;
+/** Longest accepted value of one external-system handle. */
+export declare const QA_PROFILE_MAX_IDENTITY_VALUE = 200;
+/** Most handles one profile may carry. */
+export declare const QA_PROFILE_MAX_IDENTITIES = 16;
+/** Handle keys are lowercase labels; the deployment declares which ones exist. */
+export declare const QA_PROFILE_IDENTITY_KEY: RegExp;
+/** Longest accepted display label of one declared handle field. */
+export declare const QA_PROFILE_MAX_IDENTITY_LABEL = 40;
+/** Most handle fields one deployment may declare. */
+export declare const QA_PROFILE_MAX_IDENTITY_FIELDS = 8;
+/** Default cap on the user's free-form agent guidance. */
+export declare const QA_PROFILE_DEFAULT_INSTRUCTIONS_MAX = 2000;
+/** Bounds within which a deployment may set that cap. */
+export declare const QA_PROFILE_INSTRUCTIONS_MAX_MIN = 200;
+export declare const QA_PROFILE_INSTRUCTIONS_MAX_MAX = 20000;
+/** The profile of an account that never filled one in. */
+export declare function emptyProfile(): QaAccountProfile;
+/**
+ * Read one stored (or wire-delivered) profile into its public shape. Unknown
+ * or hand-edited input degrades to the readable subset instead of throwing:
+ * a malformed profile must never cost the account its session. Overlong text
+ * is truncated here — the write path rejects it with a message instead.
+ */
+export declare function normalizeProfile(value: unknown): QaAccountProfile;
+/** Validated profile values, before the store stamps `updatedAt`. */
+export interface QaProfileWrite {
+    readonly fullName: string;
+    readonly identities: Readonly<Record<string, string>>;
+    readonly instructions: string;
+}
+export type QaProfileWriteResult = {
+    readonly ok: true;
+    readonly value: QaProfileWrite;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export interface QaProfileWriteOptions {
+    readonly instructionsMaxLength: number;
+    /**
+     * Fields the deployment declares; a write may name only these keys. Omit to
+     * check the key shape alone — the operator CLI path, where the writer is the
+     * same person who owns the configuration.
+     */
+    readonly identities?: readonly QaAccountIdentityField[];
+}
+/**
+ * Validate one full-replace profile write. Values are cleaned the same way
+ * the read path cleans them, so what a caller sends is what the prompt will
+ * later render; limits are refused with a message instead of truncated, so a
+ * user pasting an essay learns why it was not stored.
+ */
+export declare function validateProfileWrite(input: unknown, options: QaProfileWriteOptions): QaProfileWriteResult;
+export type QaIdentityFieldsResult = {
+    readonly ok: true;
+    readonly value: readonly QaAccountIdentityField[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Validate the deployment's declared handle fields: the profile form renders
+ * one input per entry and the prompt names exactly these, so a typo in a key
+ * becomes a refusal at configuration time rather than a silent no-op.
+ */
+export declare function validateIdentityFields(value: unknown): QaIdentityFieldsResult;
+//# sourceMappingURL=profile.d.ts.map

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

@@ -0,0 +1,110 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaAccounts } from "./accounts/store.js";
+import type { QaAccountIdentityField, QaAccountProfile, ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * Plugin marker on every injected message. The chat projection turns a
+ * plugin-sourced user message into injected context rather than a chat
+ * bubble, and the QA transcript keeps exactly those hidden.
+ */
+export declare const QA_NOTES_PLUGIN = "qa-surface";
+/** Note name carrying who the assistant is talking to. */
+export declare const QA_IDENTITY_NOTE = "dsh-qa-surface:user-identity";
+/** Note name carrying the deployment's rule about source provenance. */
+export declare const QA_SOURCES_NOTE = "dsh-qa-surface:structured-sources";
+export interface QaIdentityRenderInput {
+    /** The owner's account address; the one fact accounts always provide. */
+    readonly email: string;
+    readonly profile: QaAccountProfile;
+    /** Handle fields the deployment declares, in its configured order. */
+    readonly identities: readonly QaAccountIdentityField[];
+}
+/** The two identity parts one user resolves to; either may be empty. */
+export interface QaRenderedIdentity {
+    readonly identity: string;
+    readonly instructions: string;
+}
+/**
+ * Render the identity text for one attested user.
+ *
+ * The wording is deliberately explicit about provenance: these are the user's
+ * own claims, so the model is told to name the identifier it searched by and
+ * to ask when the results contradict the request. A wrong handle that the
+ * model trusts silently is the failure mode this text exists to prevent.
+ */
+export declare function renderUserIdentity(input: QaIdentityRenderInput): QaRenderedIdentity;
+/** One named block the injector can add to a step. */
+export interface QaPromptNote {
+    /** Source-section name, and the marker that finds the note again. */
+    readonly name: string;
+    readonly text: string;
+}
+export interface QaPromptNotesOptions {
+    readonly config: () => ResolvedQaSurfaceConfig;
+    /** The live accounts store, or undefined while accounts are disabled. */
+    readonly accounts: () => QaAccounts | undefined;
+    /**
+     * Whether one session belongs to the QA surface. The admission answers it:
+     * only an attested session reaches the QA audience the notes are written
+     * for, and delegated children resolve through their root session.
+     */
+    readonly isQaSession: (sessionId: string) => boolean;
+    readonly logger: PluginLogger;
+}
+/**
+ * Delivers the QA surface's ambient notes to the agent: who the assistant is
+ * talking to, and what the deployment expects around source provenance.
+ *
+ * A system-prompt section would be the natural home for both, and this plugin
+ * used one for each. Neither survives the QA deployment's own preset: the
+ * `qa-research` persona registers with `complete: true` (the persona IS the
+ * whole system prompt, so every other section is discarded) and
+ * `includeRuntimeContext: false` (which drops every context contribution as
+ * well). The preset says so outright — no plugin adds prompt text.
+ *
+ * What stays open is the conversation: a plugin-sourced user message is
+ * admitted to the request as injected context, survives both switches, and
+ * the transcript projection already hides every non-`subagent` context note
+ * from the QA audience. Each note is written once per text rather than once
+ * per step — the session's own surface is the state, so a resume or a plugin
+ * reload never duplicates a note — and written again only when its text
+ * actually changes.
+ *
+ * The notes are advisory text, never authority: nothing here is enforced by
+ * the model's compliance. The lockdown (allow-list, guards, permission
+ * preset) is host-side and holds whatever the conversation says.
+ */
+export declare class QaPromptNotes {
+    private readonly ctx;
+    private readonly options;
+    /** `${agentId}:${noteName}` → the text the note already carries. */
+    private readonly carried;
+    private readonly disposePreStep;
+    private disposed;
+    constructor(ctx: Context, options: QaPromptNotesOptions);
+    dispose(): void;
+    /** Append every note whose text this step does not already carry. */
+    private inject;
+    /** Who is asking: the owner's name, handles and their own instructions. */
+    private identityNotes;
+    /** What the deployment expects around the sources the surface collects. */
+    private sourcesNotes;
+    private carriedKey;
+    /**
+     * The text one note already carries in this agent's conversation. Process
+     * memory answers it after the first step; a cold read walks the durable
+     * surface so a resumed session or a reloaded plugin does not write twice.
+     */
+    private carriedText;
+    /**
+     * The session a chat started from. Delegated children are joined to their
+     * preset's standing scope rather than to their parent agent, so the chain
+     * has to be walked through the durable session headers; an unresolvable link
+     * (a resumed session whose parent is no longer loaded) degrades to the
+     * farthest ancestor known at that moment.
+     */
+    private rootSessionId;
+    /** The owner's email and profile, or nothing while the chat is anonymous. */
+    private identityOf;
+}
+//# sourceMappingURL=prompt-notes.d.ts.map

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

@@ -0,0 +1,26 @@
+import type { QaSourceReference, QaTurnSources, SourceExtractorContext } from "./types.js";
+import type { SourceExtractorRegistry } from "./extractors.js";
+export interface QaSourceCollectorOptions {
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly registry: SourceExtractorRegistry;
+    readonly displayScoreThreshold?: number;
+    readonly mergeFileRanges?: boolean;
+}
+/** Mutable turn-local accumulator; snapshots are immutable plain data. */
+export declare class QaSourceCollector {
+    private readonly options;
+    private readonly collected;
+    private readonly incompleteOrigins;
+    private readonly threshold;
+    constructor(options: QaSourceCollectorOptions);
+    observe(context: SourceExtractorContext): void;
+    add(sources: readonly QaSourceReference[]): void;
+    markIncomplete(origin: {
+        readonly subagentRunId?: string;
+        readonly provider?: string;
+        readonly reason: string;
+    }): void;
+    snapshot(): QaTurnSources;
+}
+//# sourceMappingURL=collector.d.ts.map

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

@@ -0,0 +1,11 @@
+import { canonicalizeUrl } from "./normalize.js";
+import type { SourceExtractor } from "./types.js";
+type UrlOptions = Parameters<typeof canonicalizeUrl>[1];
+export declare function createJiraExtractor(urlOptions?: UrlOptions): SourceExtractor;
+export declare function createConfluenceExtractor(urlOptions?: UrlOptions): SourceExtractor;
+export declare function createKnowledgeExtractor(urlOptions?: UrlOptions): SourceExtractor;
+export declare const jiraExtractor: SourceExtractor;
+export declare const confluenceExtractor: SourceExtractor;
+export declare const knowledgeExtractor: SourceExtractor;
+export {};
+//# sourceMappingURL=connectors.d.ts.map

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

@@ -0,0 +1,6 @@
+import type { QaSourceReference } from "./types.js";
+/** Merge by canonical id and rank by score, preserving first-use order on ties. */
+export declare function dedupeAndRankSources(sources: readonly QaSourceReference[], options?: {
+    readonly mergeFileRanges?: boolean;
+}): readonly QaSourceReference[];
+//# sourceMappingURL=dedupe.d.ts.map

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

@@ -0,0 +1,14 @@
+import { canonicalizeUrl } from "./normalize.js";
+import type { QaSourceReference, SourceExtractor, SourceExtractorContext } from "./types.js";
+export declare const readFileExtractor: SourceExtractor;
+export declare function createWebSearchExtractor(maxPromotedPerSearch?: number, urlOptions?: Parameters<typeof canonicalizeUrl>[1]): SourceExtractor;
+export declare function createWebFetchExtractor(urlOptions?: Parameters<typeof canonicalizeUrl>[1]): SourceExtractor;
+export declare const webFetchExtractor: SourceExtractor;
+export declare const fileSearchExtractor: SourceExtractor;
+export declare class SourceExtractorRegistry {
+    private readonly extractors;
+    register(extractor: SourceExtractor): () => void;
+    extract(context: SourceExtractorContext): readonly QaSourceReference[];
+}
+export declare function createDefaultSourceExtractorRegistry(maxPromotedPerSearch?: number, urlOptions?: Parameters<typeof canonicalizeUrl>[1]): SourceExtractorRegistry;
+//# sourceMappingURL=extractors.d.ts.map

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

@@ -0,0 +1,10 @@
+import type { QaSourceFilePreview } from "../types.js";
+export interface QaSourceFilePreviewOptions {
+    readonly root: string;
+    readonly sourcePath: string;
+    readonly maxBytes: number;
+    readonly maxMarkdownRenderBytes: number;
+}
+/** Read one canonical in-root file without following a symlink outside root. */
+export declare function readSourceFilePreview({ root, sourcePath, maxBytes, maxMarkdownRenderBytes, }: QaSourceFilePreviewOptions): Promise<QaSourceFilePreview>;
+//# sourceMappingURL=file-preview.d.ts.map

package/lib/types/provenance/host-store.d.ts

@@ -0,0 +1,54 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { QaTurnSources } from "./types.js";
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+export declare const QA_REPORT_SOURCES_TOOL = "qa_report_sources";
+declare module "@deepseek-ai/dsh-session" {
+    interface SessionEventMap {
+        "qa/sources": QaTurnSources;
+    }
+}
+interface SubagentInfo {
+    readonly runId: string;
+    readonly provider: string;
+    readonly id: string;
+    readonly local: boolean;
+}
+declare module "@deepseek-ai/cordis" {
+    interface Events {
+        "subagent/start"(info: SubagentInfo): void;
+        "subagent/end"(info: SubagentInfo): void;
+    }
+}
+/** Host authority for collection, replay, delegation inheritance and snapshots. */
+export declare class QaProvenanceHost {
+    private readonly ctx;
+    private readonly config;
+    private readonly collectors;
+    private readonly snapshots;
+    private readonly calls;
+    private readonly lineage;
+    private readonly disposers;
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig);
+    dispose(): void;
+    /**
+     * Drop every per-session record of one chat. Long-lived servers outlive
+     * their sessions by weeks; without this the collector, snapshot, call and
+     * lineage maps grow with every chat and turn forever.
+     */
+    private forget;
+    private forgetAll;
+    bundles(sessionId: string): readonly QaTurnSources[];
+    sourceAllowed(sessionId: string, path: string): boolean;
+    private seed;
+    private observeEvent;
+    private shouldCollect;
+    private materialize;
+    private startSubagent;
+    private endSubagent;
+    private registerReportTool;
+    private collector;
+    private sessionCalls;
+    private sessionSnapshots;
+}
+export {};
+//# sourceMappingURL=host-store.d.ts.map

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

@@ -0,0 +1,10 @@
+export * from "./collector.js";
+export * from "./connectors.js";
+export * from "./dedupe.js";
+export * from "./extractors.js";
+export * from "./file-preview.js";
+export * from "./host-store.js";
+export * from "./normalize.js";
+export * from "./reported.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,13 @@
+import type { QaSourceLocation } from "./types.js";
+/** Strip model-added XML-like wrappers without interpreting arbitrary prose. */
+export declare function unwrapSourceTarget(value: string): string;
+/** Canonical HTTP(S) identity while retaining business-relevant parameters. */
+export declare function canonicalizeUrl(value: string, options?: {
+    readonly normalize?: boolean;
+    readonly stripTrackingParams?: boolean;
+}): string | null;
+/** Normalize separators and, when possible, make a path workspace-relative. */
+export declare function canonicalizeWorkspacePath(value: string, workspaceRoot?: string): string;
+/** Union exact anchors and compact overlapping or adjacent ranges. */
+export declare function compactLocations(locations: readonly QaSourceLocation[]): readonly QaSourceLocation[];
+//# sourceMappingURL=normalize.d.ts.map

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

@@ -0,0 +1,5 @@
+import { canonicalizeUrl } from "./normalize.js";
+import type { QaReportedSource, QaSourceOrigin, QaSourceReference } from "./types.js";
+/** Normalize a source explicitly reported by a delegated provider. */
+export declare function normalizeReportedSource(source: QaReportedSource, origin: QaSourceOrigin, workspaceRoot?: string, urlOptions?: Parameters<typeof canonicalizeUrl>[1]): QaSourceReference | null;
+//# sourceMappingURL=reported.d.ts.map

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

@@ -0,0 +1,78 @@
+export type QaSourceKind = "file" | "code" | "web" | "jira" | "confluence" | "knowledge" | "other";
+export type QaSourceEvidence = "read" | "fetched" | "queried" | "reported" | "inherited" | "discovered";
+export type QaSourceMetadataValue = string | number | boolean | null | readonly QaSourceMetadataValue[] | {
+    readonly [key: string]: QaSourceMetadataValue;
+};
+export interface QaSourceMetadata {
+    readonly [key: string]: QaSourceMetadataValue;
+}
+export interface QaSourceLocation {
+    readonly path?: string;
+    readonly lineStart?: number;
+    readonly lineEnd?: number;
+    readonly anchor?: string;
+    readonly jiraKey?: string;
+    readonly confluencePageId?: string;
+}
+export interface QaSourceOrigin {
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly step?: number;
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly agentId?: string;
+    readonly role: "parent" | "subagent";
+    readonly subagentRunId?: string;
+    readonly subagentSessionId?: string;
+}
+export interface QaSourceReference {
+    /** Stable identity after path, URL or provider-specific normalization. */
+    readonly id: string;
+    readonly kind: QaSourceKind;
+    readonly title: string;
+    readonly uri?: string;
+    readonly path?: string;
+    readonly snippet?: string;
+    readonly locations: readonly QaSourceLocation[];
+    readonly evidence: QaSourceEvidence;
+    readonly origins: readonly QaSourceOrigin[];
+    readonly score: number;
+    readonly metadata?: QaSourceMetadata;
+}
+export interface QaTurnSources {
+    readonly version: 1;
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly sources: readonly QaSourceReference[];
+    readonly discovered?: readonly QaSourceReference[];
+    readonly complete: boolean;
+    readonly incompleteOrigins?: readonly {
+        readonly subagentRunId?: string;
+        readonly provider?: string;
+        readonly reason: string;
+    }[];
+}
+export interface SourceExtractorContext {
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly result: unknown;
+    readonly presentation?: unknown;
+    readonly origin: QaSourceOrigin;
+    /** Canonical session/workspace root used to make local paths portable. */
+    readonly workspaceRoot?: string;
+}
+export interface QaReportedSource {
+    readonly kind: QaSourceKind;
+    readonly title: string;
+    readonly uri?: string;
+    readonly path?: string;
+    readonly snippet?: string;
+    readonly locations?: readonly QaSourceLocation[];
+    readonly metadata?: QaSourceMetadata;
+}
+export interface SourceExtractor {
+    readonly id: string;
+    matches(context: SourceExtractorContext): boolean;
+    extract(context: SourceExtractorContext): readonly QaSourceReference[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/resolve-config.d.ts

@@ -1,6 +1,11 @@
+import { normalizeRoutePath } from "./config-resolvers/basics.js";
+import { DEFAULT_QA_SURFACE_CONFIG } from "./config-resolvers/defaults.js";
 import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
-export declare const DEFAULT_QA_SURFACE_CONFIG: ResolvedQaSurfaceConfig;
-export declare function normalizeRoutePath(value: string): string;
-/** Materialize defaults and enforce route/session/model safety constraints. */
+export { DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath };
+/**
+ * Materialize defaults and enforce route/session/model safety constraints by
+ * running one resolver per config domain — in the order the checks have
+ * always fired — and assembling the frozen result.
+ */
 export declare function resolveConfig(input?: QaSurfaceConfig): ResolvedQaSurfaceConfig;
 //# sourceMappingURL=resolve-config.d.ts.map

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

@@ -1,6 +1,17 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * The accounts half of admission, resolved per call by the entry (accounts
+ * may be toggled at runtime). A gate must either accept the token/session
+ * pair or throw the coarse `QaAttestationError`; see {@link QaAccounts}.
+ */
+export interface QaAccountsGate {
+    enforceSessionAccess(token: string, sessionId: string): {
+        readonly id: string;
+    } | undefined;
+    userWorkspace(userId: string, registeredWorkspacePath: string): string;
+}
 /**
  * Host-side QA policy admission boundary — the only browser-callable operation
  * that turns a session into a locked QA session. It verifies the immutable
@@ -13,9 +24,32 @@ export declare class QaPolicyAdmission {
     private readonly ctx;
     private readonly config;
     private readonly logger;
+    private readonly accounts?;
     private readonly appliedPolicies;
-    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger);
-    secureSession(sessionId: string): QaLockdownProof;
+    /**
+     * Sessions the QA surface has attested. The provenance note is written for
+     * exactly these, and a delegated child resolves through its root session, so
+     * one set answers for the whole chat.
+     */
+    private readonly attested;
+    private readonly workspaceRoots;
+    private readonly disposeWorkspaceGuard;
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined);
+    /**
+     * The mounted attachment store's verbatim root, when the backend exposes
+     * one. It sits outside every workspace, so the per-user fence would
+     * otherwise deny the model the exact file an upload produced and the prompt
+     * points it at. A backend without a resolvable root simply keeps the fence
+     * closed — attachments then only work where reads are not fenced per user.
+     */
+    private attachmentRoot;
+    secureSession(token: string, sessionId: string): QaLockdownProof;
+    /**
+     * Whether one session went through this boundary. The provenance note is
+     * written only for attested sessions, which is what keeps a deployment's
+     * source rules out of unrelated chats served by the same process.
+     */
+    knowsSession(sessionId: string): boolean;
     /** Detach every pinned tool policy; wired as a disposal effect by the entry. */
     dispose(): void;
 }

package/lib/types/shared/session-key.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The browser-local key namespace every QA-side index derives from: the
+ * configured storage key pinned to the served route, versioned once so the
+ * Host's head-script injection and the client bundle cannot drift apart.
+ *
+ * Dependency-free like every `src/shared` module: both bundles inline it.
+ */
+/**
+ * The versioned key prefix for browser-local QA state of one deployment.
+ * Callers append their own scope suffix (`:account-token`, `:welcome-notice`,
+ * `:chat:<id>`, …).
+ * @param config - configuration holding the storage key and the route path.
+ * @returns the versioned prefix, e.g. `dsh-qa-surface.session:v1:/qa`.
+ */
+export declare function qaStorageNamespace(config: Readonly<{
+    session: {
+        storageKey: string;
+    };
+    route: {
+        path: string;
+    };
+}>): string;
+//# sourceMappingURL=session-key.d.ts.map

package/lib/types/shared/settings.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Identity shared by the Host plugin and its browser settings card.
+ *
+ * This module must stay dependency-free: the card bundle inlines it, and a
+ * browser build must not pull the Host config surface (schemastery) into the
+ * page just to learn the namespace name.
+ */
+/** Settings namespace the QA surface owns and its card binds to. */
+export declare const QA_SURFACE_SETTINGS_NAMESPACE = "qa-surface";
+//# sourceMappingURL=settings.d.ts.map