@yadsh/dsh-qa-surface 0.5.0 → 0.6.0

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

@@ -0,0 +1,47 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaToolActivation, QaToolActivationOrigin, QaToolActivationResult, QaToolDescriptor } from "./types.js";
+export interface QaToolActivationManagerOptions {
+    /** Live catalog; read per activation so a reload sees the new set. */
+    readonly catalog: readonly QaToolDescriptor[];
+    readonly catalogVersion: string;
+    readonly logger: PluginLogger;
+}
+/**
+ * Per-agent runtime ownership of the QA tool registrations.
+ *
+ * One agent's tools exist only while that agent is live: activation registers
+ * the whole catalog through the agent's own scoped context, and disposal
+ * unwinds the exact disposers `tools.register()` returned. State is a WeakMap
+ * keyed by the live agent, so nothing has to be keyed by id and a stale agent
+ * can never be mistaken for a resumed one.
+ */
+export declare class QaToolActivationManager implements QaToolActivation {
+    private readonly options;
+    private readonly states;
+    constructor(options: QaToolActivationManagerOptions);
+    /**
+     * Register the whole catalog on one agent, all or nothing.
+     *
+     * A failed registration unwinds every tool this attempt registered and leaves
+     * the agent inactive: a partially attached QA surface would be worse than
+     * none, because the model would see a tool it cannot rely on.
+     * @param agent - the live agent receiving the tools.
+     * @param origin - why activation ran, for the operator log.
+     * @returns the outcome; `failed` carries the original error for the caller to report.
+     */
+    activate(agent: Agent, origin: QaToolActivationOrigin): QaToolActivationResult;
+    /** Whether this agent currently has the QA tools registered. */
+    isActive(agent: Agent): boolean;
+    /** Names registered on this agent; the admission guard evaluates this per call. */
+    activeToolNames(agent: Agent): readonly string[];
+    /**
+     * Unregister one agent's QA tools and forget its state. Safe to call more
+     * than once, and safe for an agent that never activated.
+     * @param agent - the agent whose registrations must be unwound.
+     */
+    disposeAgent(agent: Agent): void;
+    /** Dispose in reverse registration order, containing individual failures. */
+    private rollback;
+}
+//# sourceMappingURL=activation-manager.d.ts.map

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

@@ -0,0 +1,40 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { QaToolDescriptor } from "./types.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
+ * persisted record; it is reported by `qa_tools_selfcheck` and by the operator
+ * log so a catalog change is visible in a running deployment.
+ *
+ * Bump it whenever the catalog's tool set or their schemas change.
+ */
+export declare const QA_TOOL_CATALOG_VERSION = "1";
+/** One QA tool reports the activation state of whichever agent calls it. */
+export interface QaToolsSelfcheckDeps {
+    readonly catalogVersion: string;
+    readonly activationMode: string;
+    /** Names the catalog contributes, in catalog order. */
+    readonly catalogTools: () => readonly string[];
+    /** Names currently registered on the calling agent. */
+    readonly activeTools: (agent: Agent) => readonly string[];
+    /** Whether the calling agent's session shows the activation skill was loaded. */
+    readonly skillLoaded: (agent: Agent) => boolean;
+}
+/**
+ * Build the shipped QA tool catalog.
+ *
+ * Side-effect free: constructing it registers nothing with `ctx.tools`. The
+ * activation manager owns every registration.
+ */
+export declare function createQaToolCatalog(deps: QaToolsSelfcheckDeps): readonly QaToolDescriptor[];
+/** QA tool names, in catalog order; the admission gate treats them as dynamic. */
+export declare function qaToolNames(catalog: readonly QaToolDescriptor[]): string[];
+/**
+ * Validate the catalog before it is registered anywhere: names must be unique
+ * and non-empty. Called once at activation preflight so a broken catalog fails
+ * before the first registration rather than halfway through.
+ * @param catalog - descriptors to validate.
+ * @throws when two descriptors share a name or a name is empty.
+ */
+export declare function assertValidQaToolCatalog(catalog: readonly QaToolDescriptor[]): void;
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/qa-tools/durable-marker.d.ts

@@ -0,0 +1,16 @@
+import type { Session } from "@deepseek-ai/dsh-session";
+/**
+ * Whether one session's log shows the configured skill was successfully loaded.
+ *
+ * Pairs each `tool/call` for the `skill` tool with its `tool/result`, then reads
+ * the loaded skill's name from the canonical rendered content. The rendered
+ * block is the only record of the returned skill identity that survives to the
+ * log — `tool/result` stores the model-facing message, not the tool's canonical
+ * value — and the pair closes only on a non-error result, so a refused or
+ * failed load never counts.
+ * @param session - the live session to inspect.
+ * @param skillName - the configured activation skill name.
+ * @returns whether that skill was loaded and its result succeeded.
+ */
+export declare function sessionLoadedSkill(session: Pick<Session, "snapshotEvents">, skillName: string): boolean;
+//# sourceMappingURL=durable-marker.d.ts.map

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

@@ -0,0 +1,40 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaToolActivation } from "./types.js";
+export interface QaToolsOptions {
+    readonly logger: PluginLogger;
+    readonly dynamicActivation: boolean;
+    readonly activationSkill: string;
+    readonly activationMode: string;
+    readonly activationPresets: readonly string[];
+}
+/**
+ * The QA tool subsystem: one catalog, one per-agent activation manager, and the
+ * two edges that drive it — the skill-result detector and the agent lifecycle.
+ *
+ * `dsh-qa-surface` owns the tools but never registers them at boot. Nothing in
+ * the catalog reaches the model until an agent it belongs to loads the
+ * activation skill, so the initial request of a session carries only the
+ * composition's own schemas.
+ */
+export declare class QaTools implements QaToolActivation {
+    private readonly ctx;
+    private readonly options;
+    private readonly manager;
+    private readonly detector;
+    private readonly lifecycle;
+    private readonly catalogTools;
+    constructor(ctx: Context, options: QaToolsOptions);
+    /** Names currently registered on one agent; the admission guard reads this per call. */
+    activeToolNames(agent: Agent): readonly string[];
+    dispose(): void;
+    /**
+     * The preset gate. An empty `activationPresets` leaves it open, which is only
+     * coherent when this plugin serves a single agent composition; naming the QA
+     * preset keeps an unrelated DSH agent from unlocking the same catalog by
+     * loading a skill of the same name.
+     */
+    private isManagedAgent;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,44 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaToolActivationManager } from "./activation-manager.js";
+export interface QaToolActivationLifecycleOptions {
+    readonly manager: QaToolActivationManager;
+    readonly logger: PluginLogger;
+    /** Whether this agent's composition participates in QA tool activation. */
+    readonly isManagedAgent: (agent: Agent) => boolean;
+    /**
+     * `true` waits for the activation skill; `false` attaches the catalog to
+     * every managed agent as soon as it is created.
+     */
+    readonly dynamicActivation: boolean;
+    /** The skill name whose load unlocks the tools in dynamic mode. */
+    readonly activationSkill: string;
+}
+/**
+ * Owns the arrival and departure edges of one agent's QA tool surface.
+ *
+ * Arrival: in dynamic mode a resumed session is recognized by the durable
+ * marker in its own log and gets its current catalog back before the first
+ * model step, while a fresh session waits for the detector. In immediate mode
+ * every managed agent is served at creation.
+ *
+ * Departure: the exact registrations this plugin made are unwound when the
+ * agent is disposed, so an agent that leaves never leaves a scoped tool behind.
+ */
+export declare class QaToolActivationLifecycle {
+    private readonly ctx;
+    private readonly options;
+    private readonly disposers;
+    constructor(ctx: Context, options: QaToolActivationLifecycleOptions);
+    /**
+     * Restore a resumed activation, or attach immediately in the compatibility
+     * mode. A fresh managed session ends this handler inactive by design: the
+     * tools arrive when the model loads the activation skill.
+     */
+    private onAgentCreated;
+    private attach;
+    private onAgentDisposed;
+    dispose(): void;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1,45 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/**
+ * One entry of the QA tool catalog.
+ *
+ * `group` and `tags` are passive metadata: the MVP activation policy activates
+ * the whole catalog and never filters on them. They exist so a later
+ * `activationMode` can select subsets without touching the tool definitions.
+ */
+export interface QaToolDescriptor {
+    readonly definition: ToolDefinition;
+    /** Capability bucket reserved for a future grouped activation mode. */
+    readonly group?: string;
+    /** Free-form labels reserved for a future search/unlock mode. */
+    readonly tags?: readonly string[];
+}
+/** Why one activation ran; the origin only shapes logging and the event guard. */
+export type QaToolActivationOrigin = "skill" | "restore" | "immediate";
+/** Runtime activation state of one live agent. */
+export interface QaToolActivationState {
+    status: "inactive" | "activating" | "active";
+    /** Catalog version whose tools are registered; set once `status` is active. */
+    catalogVersion?: string | undefined;
+    /** Exact disposers returned by `tools.register()`, in registration order. */
+    disposers: (() => void)[];
+}
+/** Outcome of one activation attempt. */
+export type QaToolActivationResult = {
+    readonly status: "activated";
+    readonly count: number;
+} | {
+    readonly status: "already-active";
+} | {
+    readonly status: "failed";
+    readonly error: unknown;
+};
+/** The activation subsystem's observable surface, injected into the admission gate. */
+export interface QaToolActivation {
+    /**
+     * Names currently registered on one live agent. The admission guard evaluates
+     * this per execution, so a tool becomes callable exactly when it appears here.
+     */
+    activeToolNames(agent: Agent): readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -1,3 +1,4 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
@@ -25,7 +26,15 @@ export declare class QaPolicyAdmission {
     private readonly config;
     private readonly logger;
     private readonly accounts?;
+    /**
+     * Names the QA tool catalog attached to one agent after its activation
+     * skill loaded. Read per execution, so a tool becomes callable exactly when
+     * it is registered and stops being callable once the agent is disposed.
+     */
+    private readonly dynamicToolNames;
     private readonly appliedPolicies;
+    /** Host-trusted principal-scoped plugin tools enabled outside static config. */
+    private readonly principalScopedTools;
     /**
      * Sessions the QA surface has attested. The provenance note is written for
      * exactly these, and a delegated child resolves through its root session, so
@@ -34,15 +43,28 @@ export declare class QaPolicyAdmission {
     private readonly attested;
     private readonly workspaceAccess;
     private readonly disposeWorkspaceGuard;
-    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined);
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined, 
+    /**
+     * Names the QA tool catalog attached to one agent after its activation
+     * skill loaded. Read per execution, so a tool becomes callable exactly when
+     * it is registered and stops being callable once the agent is disposed.
+     */
+    dynamicToolNames?: (agent: Agent) => readonly string[]);
+    /**
+     * Add tools whose own executor resolves the QA principal server-side.
+     * Enabling the contributing plugin is the operator decision; model arguments
+     * still cannot select an owner. The returned disposer mirrors tool lifetime.
+     */
+    registerPrincipalScopedTools(names: readonly string[]): () => void;
     /**
      * 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.
+     * Source preview asks for the same root, so one upload is readable by both.
      */
-    private attachmentRoot;
+    attachmentRoot(): string | undefined;
     /**
      * The live agent for one session, resuming a Session the Host has not
      * materialized in this process.

package/lib/types/starters.d.ts

@@ -0,0 +1,45 @@
+import type { QaAccountStarters, QaAccountStartersInput, QaAccountStarter } from "./types.js";
+/**
+ * Per-account starter messages: the labeled buttons above an empty composer,
+ * and what each of them sends. Shape, limits, and the normalization both
+ * halves of the plugin agree on. Deliberately free of Node built-ins — the
+ * accounts store and the browser-side form import these same rules, the same
+ * way profile.ts does for the self-declared identity.
+ */
+/** Most starter buttons one account may store. */
+export declare const QA_STARTERS_MAX_ITEMS = 12;
+/** Longest accepted button label. */
+export declare const QA_STARTERS_MAX_LABEL = 80;
+/** Longest accepted prompt one button sends. */
+export declare const QA_STARTERS_MAX_PROMPT = 2000;
+/** The starters of an account that never customized them. */
+export declare function emptyStarters(): QaAccountStarters;
+/**
+ * Read one stored (or wire-delivered) starters record into its public shape.
+ * Unknown or hand-edited input degrades to the readable subset instead of
+ * throwing, mirroring the profile read path: a malformed record must never
+ * cost the account its session.
+ */
+export declare function normalizeStarters(value: unknown): QaAccountStarters;
+/** Validated starters values, before the store persists them. */
+export type QaStartersWrite = QaAccountStartersInput;
+export type QaStartersWriteResult = {
+    readonly ok: true;
+    readonly value: QaStartersWrite;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Validate one full-replace starters write. Values are cleaned the same way
+ * the read path cleans them, but limits are refused with a message instead of
+ * truncated, so a user pasting an essay learns why it was not stored.
+ */
+export declare function validateStartersWrite(input: unknown): QaStartersWriteResult;
+/**
+ * The buttons an empty composer shows: the account's own starters first,
+ * then the deployment's suggestions unless the account hid them. An anonymous
+ * visitor (no starters of their own) sees exactly the deployment's list.
+ */
+export declare function effectiveQuickQuestions(own: QaAccountStarters | undefined, defaults: readonly string[]): readonly QaAccountStarter[];
+//# sourceMappingURL=starters.d.ts.map

package/lib/types/types.d.ts

@@ -1,8 +1,15 @@
+import type { QaDocumentsConfig, ResolvedQaDocumentsConfig } from "./documents/config.js";
 import type { QaTurnSources } from "./provenance/types.js";
 export type QaSessionPolicy = "browser-persistent" | "new-on-load" | "fixed";
 export type QaSandboxMode = "read-only" | "workspace-write";
 export type QaApprovalPolicy = "never";
 export type QaToolPolicyMode = "allow-list";
+/**
+ * How the QA tool catalog is attached. `all` attaches the whole catalog once
+ * the activation skill loads; the field is reserved so a future grouped or
+ * searched mode needs no config redesign.
+ */
+export type QaToolActivationMode = "all";
 /**
  * How a tool policy `ask` resolves on an attested QA agent. `blocked` refuses
  * the call with the surface's own reason; `interactive` parks it until the
@@ -34,6 +41,8 @@ export interface QaAccountUserPublic {
     readonly disabled: boolean;
     /** Self-declared identity the QA prompt renders; empty until edited. */
     readonly profile: QaAccountProfile;
+    /** The account's own starter buttons; empty until customized. */
+    readonly starters: QaAccountStarters;
 }
 /** One external system the deployment collects a handle for. */
 export interface QaAccountIdentityField {
@@ -63,6 +72,26 @@ export interface QaAccountProfileInput {
     readonly identities: Readonly<Record<string, string>>;
     readonly instructions: string;
 }
+/** One starter button: what it reads and what pressing it sends. */
+export interface QaAccountStarter {
+    readonly label: string;
+    readonly prompt: string;
+}
+/**
+ * An account's own starter buttons plus the choice about the deployment's
+ * built-in suggestions. Pure UI preferences: unlike the profile, none of this
+ * reaches the agent prompt.
+ */
+export interface QaAccountStarters {
+    readonly items: readonly QaAccountStarter[];
+    /** Hide the deployment's suggested questions in this account's composer. */
+    readonly hideDefaults: boolean;
+}
+/** Full-replace starters write: an absent value clears the stored one. */
+export interface QaAccountStartersInput {
+    readonly items: readonly QaAccountStarter[];
+    readonly hideDefaults: boolean;
+}
 /** One successful login/registration: the bearer token plus the user. */
 export interface QaAccountSession {
     readonly token: string;
@@ -91,6 +120,90 @@ export interface QaOwnershipEntry {
     readonly displayName: string;
     readonly claimedAt: string;
 }
+/**
+ * Why one skill draft cannot be saved, or why it saves with a caveat. Codes
+ * stay stable on the wire; the browser owns the Russian copy.
+ */
+export type QaSkillDiagnosticCode = "name-required" | "name-invalid" | "name-mismatch" | "description-required" | "description-too-long" | "when-to-use-too-long" | "field-type-invalid" | "invocation-never" | "invocation-invalid" | "invocation-legacy-key" | "allowed-tools-invalid" | "tool-name-invalid" | "tool-unavailable" | "tools-too-many" | "file-too-large" | "frontmatter-missing" | "skill-file-missing" | "frontmatter-invalid" | "unknown-field" | "resource-unsupported";
+/** One finding about a skill file or an editor draft. */
+export interface QaSkillDiagnostic {
+    readonly code: QaSkillDiagnosticCode;
+    readonly severity: "error" | "warning";
+    /** The editor field the message belongs to, or null for a file-wide one. */
+    readonly field: string | null;
+    /** The offending value: a tool name, a frontmatter key, a limit. */
+    readonly detail: string | null;
+}
+/**
+ * A JSON-representable frontmatter value. The editor receives the preserved
+ * foreign fields verbatim over the Host bridge, which carries JSON only, so
+ * the parser drops anything a YAML document can hold but JSON cannot.
+ */
+export type QaSkillJsonValue = string | number | boolean | null | readonly QaSkillJsonValue[] | {
+    readonly [key: string]: QaSkillJsonValue;
+};
+/** One personal skill as the catalog list renders it. */
+export interface QaSkillSummary {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    /** Declared tools, in canonical order; unknown ones included. */
+    readonly allowedTools: readonly string[];
+    /** Declared tools the current QA scope cannot use; still stored as declared. */
+    readonly unavailableTools: readonly string[];
+    /** Entries in the skill directory besides SKILL.md (references, assets, …). */
+    readonly resourceCount: number;
+    readonly valid: boolean;
+    readonly diagnostics: readonly QaSkillDiagnostic[];
+    readonly updatedAt: string | null;
+    /** sha256 of the stored bytes; an update must echo the revision it read. */
+    readonly revision: string;
+}
+/** One personal skill with everything the editor needs. */
+export interface QaSkillDocument extends QaSkillSummary {
+    readonly body: string;
+    /** Frontmatter the editor preserves but does not own. */
+    readonly extraFrontmatter: Readonly<Record<string, QaSkillJsonValue>>;
+    /** Absolute SKILL.md path; rendered read-only for advanced users. */
+    readonly sourcePath: string;
+    /** The canonical file the serializer writes, built from the parsed content. */
+    readonly preview: string;
+}
+/** One tool the picker can offer, with this deployment's availability. */
+export interface QaSkillToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    /** False when the QA session's own scope cannot use the tool. */
+    readonly available: boolean;
+}
+/** The editor's save payload. */
+export interface QaSkillDraftInput {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    readonly allowedTools: readonly string[];
+    readonly body: string;
+    /** Echo of the revision the editor read; a stale one is refused. */
+    readonly expectedRevision: string | null;
+}
+/**
+ * The Host's answer about one unsaved draft: the file a save would write and
+ * the diagnostics it found. The editor shows its own subset immediately and
+ * this authoritative set as soon as it arrives.
+ */
+export interface QaSkillValidation {
+    readonly preview: string;
+    readonly diagnostics: readonly QaSkillDiagnostic[];
+}
+/** What one delete did: v1 keeps the directory recoverable. */
+export interface QaSkillRemoval {
+    readonly name: string;
+    readonly trashed: boolean;
+}
 export interface QaSourcesConfig {
     readonly enabled?: boolean;
     readonly collect?: {
@@ -174,6 +287,11 @@ export interface QaSurfaceConfig {
         /** Floor for the visitor-resizable transcript/composer width; the page caps it. */
         readonly minContentWidth?: number;
         readonly showSessionList?: boolean;
+        /**
+         * Sign subagent completion notices with deterministic codenames
+         * («Дотошный Барсук») instead of the child's readable name or raw id.
+         */
+        readonly subagentCodenames?: boolean;
     };
     readonly suggestedQuestions?: readonly string[];
     /**
@@ -185,6 +303,27 @@ export interface QaSurfaceConfig {
         readonly approvals?: QaApprovalInteraction;
         readonly questions?: QaQuestionInteraction;
     };
+    /**
+     * QA tool delivery. Dynamic activation keeps the QA tool schemas out of the
+     * model request until the activation skill has actually been loaded.
+     */
+    readonly tools?: {
+        /**
+         * `true` attaches the QA tools only after the activation skill loads;
+         * `false` attaches them to every managed agent at creation.
+         */
+        readonly dynamicActivation?: boolean;
+        /** The skill name whose successful load attaches the QA tools. */
+        readonly activationSkill?: string;
+        /** Accepted activation policy; only `all` is implemented. */
+        readonly activationMode?: QaToolActivationMode;
+        /**
+         * Agent presets whose sessions participate. An empty list leaves the gate
+         * open, which is only safe when this plugin serves one agent composition —
+         * name the QA preset in any deployment that composes more than one.
+         */
+        readonly activationPresets?: readonly string[];
+    };
     readonly lockdown?: {
         readonly enabled?: boolean;
         readonly enforceFixedAgentPreset?: boolean;
@@ -222,6 +361,20 @@ export interface QaSurfaceConfig {
          * The child directory is not registered as a separate DSH workspace.
          */
         readonly perUserWorkspace?: boolean;
+        /**
+         * Personal Skills: the user's own `.dsh/skills` below their QA workspace,
+         * surfaced through a skill provider this plugin owns.
+         */
+        readonly skills?: {
+            readonly enabled?: boolean;
+            /** Directory below the personal root; relative, never escaping it. */
+            readonly relativeRoot?: string;
+            /** Follow manual file edits and refresh the DSH catalog. */
+            readonly watch?: boolean;
+            readonly maxSkillBytes?: number;
+            /** Reserved for the resource editor; v1 edits SKILL.md only. */
+            readonly allowResourceEditing?: boolean;
+        };
         /** Self-declared profile: storage, the owner's form, and prompt injection. */
         readonly profile?: {
             readonly enabled?: boolean;
@@ -235,6 +388,10 @@ export interface QaSurfaceConfig {
             /** Character cap on the user's free-form agent guidance. */
             readonly instructionsMaxLength?: number;
         };
+        /** Per-account starter buttons above an empty composer. */
+        readonly starters?: {
+            readonly enabled?: boolean;
+        };
     };
     readonly entry?: {
         /** Inject the root → /qa redirect for non-loopback hostnames. */
@@ -244,6 +401,8 @@ export interface QaSurfaceConfig {
     };
     readonly sources?: QaSourcesConfig;
     readonly attachments?: QaAttachmentsConfig;
+    /** Document pipeline: creation, conversion and extraction (see documents/). */
+    readonly documents?: QaDocumentsConfig;
 }
 /** What a QA visitor may attach to one message. */
 export interface QaAttachmentsConfig {
@@ -299,6 +458,7 @@ export interface ResolvedQaSurfaceConfig {
         readonly renderMarkdown: boolean;
         readonly minContentWidth: number;
         readonly showSessionList: boolean;
+        readonly subagentCodenames: boolean;
     };
     readonly suggestedQuestions: readonly string[];
     readonly thinkingPhrases: readonly string[];
@@ -342,11 +502,33 @@ export interface ResolvedQaSurfaceConfig {
             readonly identities: readonly QaAccountIdentityField[];
             readonly instructionsMaxLength: number;
         };
+        /** Per-account starter buttons above an empty composer. */
+        readonly starters: {
+            readonly enabled: boolean;
+        };
+        /**
+         * Personal Skills. Resolution turns the flag off on any deployment that
+         * cannot give every account its own directory: the storage root is the
+         * account's own workspace, so there is no safe shared fallback.
+         */
+        skills: {
+            readonly enabled: boolean;
+            readonly relativeRoot: string;
+            readonly watch: boolean;
+            readonly maxSkillBytes: number;
+            readonly allowResourceEditing: boolean;
+        };
     };
     readonly entry: {
         readonly redirectNonLoopback: boolean;
         readonly cookieBootstrap: boolean;
     };
+    readonly tools: {
+        readonly dynamicActivation: boolean;
+        readonly activationSkill: string;
+        readonly activationMode: QaToolActivationMode;
+        readonly activationPresets: readonly string[];
+    };
     readonly sources: {
         readonly enabled: boolean;
         readonly collect: {
@@ -395,6 +577,7 @@ export interface ResolvedQaSurfaceConfig {
         readonly maxPending: number;
         readonly extensions: readonly string[];
     };
+    readonly documents: ResolvedQaDocumentsConfig;
 }
 export interface QaSourceFilePreview {
     readonly path: string;
@@ -417,11 +600,12 @@ export interface QaLockdownProof {
     readonly toolPolicyLoaded: boolean;
     readonly toolAllowList: readonly string[];
 }
-export type QaMessage = {
+export interface QaUserMessage {
     readonly id: string;
     readonly role: "user";
     readonly text: string;
-    readonly status: "committed";
+    /** `pending` is a browser-only optimistic row until the Host emits it. */
+    readonly status: "pending" | "committed";
     readonly timestamp?: number;
     readonly images?: readonly QaImageView[];
     /** Durable files the user attached to this message, in prompt order. */
@@ -431,7 +615,12 @@ export type QaMessage = {
      * chat; the owner themself sees their messages unlabeled.
      */
     readonly author?: string;
-} | {
+}
+/** Browser-only user row shown while the Host prepares the accepted turn. */
+export type QaPendingUserMessage = Omit<QaUserMessage, "status"> & {
+    readonly status: "pending";
+};
+export type QaMessage = QaUserMessage | {
     readonly id: string;
     readonly role: "assistant";
     readonly text: string;
@@ -462,6 +651,8 @@ export type QaMessage = {
     readonly notice?: {
         readonly title: string;
         readonly body: string;
+        /** Muted correlation line above the body (task name, session id). */
+        readonly meta?: string;
     };
 } | {
     readonly id: string;
@@ -528,6 +719,8 @@ export type QaAttachmentDraft = QaImageDraft | QaFileDraft;
 export interface QaImageView {
     readonly attachmentId: string;
     readonly mediaType: QaImageMediaType;
+    /** Browser-local thumbnail URL, present only on an optimistic message. */
+    readonly previewUrl?: string;
 }
 /**
  * A durable file attached to a sent message. The browser never reads these
@@ -592,6 +785,8 @@ export interface QaSessionState {
     readonly phase: QaSessionPhase;
     readonly sessionId: string | null;
     readonly messages: readonly QaMessage[];
+    /** Immediate send feedback, kept outside the durable transcript. */
+    readonly pendingMessage: QaPendingUserMessage | null;
     readonly error: string | null;
     readonly canSend: boolean;
     readonly canStop: boolean;
@@ -608,4 +803,8 @@ export interface QaSessionState {
     /** Question requests parked for the operator's answer, oldest first. */
     readonly questions: readonly QaPendingQuestion[];
 }
+/** Minimal server-trusted identity exposed to principal-scoped plugins. */
+export interface QaPrincipal {
+    readonly userId: string;
+}
 //# sourceMappingURL=types.d.ts.map