@yadsh/dsh-qa-surface 0.5.0 → 0.6.0

package/lib/types/personal-skills/paths.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Filesystem boundary of the personal-skills feature.
+ *
+ * Every path is derived, never accepted: the browser names a skill, the Host
+ * combines the authenticated account's own workspace directory with the
+ * configured relative root, and each step re-checks that the canonical result
+ * still sits below that account's root. Symlinked directories are refused
+ * rather than followed, so a link planted inside the personal root cannot
+ * move reads or writes to another account's storage.
+ *
+ * `.dsh/skills-trash` is the removal destination: the last segment of the
+ * configured relative root with a `-trash` suffix, so a deployment that moved
+ * its skill directory keeps the trash beside it.
+ */
+export declare const QA_SKILL_TRASH_SUFFIX = "-trash";
+export interface QaSkillRoots {
+    /** The canonical account root every derived path must stay inside. */
+    readonly personalRoot: string;
+    /** The canonical directory holding one subdirectory per skill. */
+    readonly skills: string;
+    /** The canonical directory a removed skill directory is moved into. */
+    readonly trash: string;
+}
+/** Derive and verify every directory the feature touches for one account. */
+export declare function resolveSkillRoots(personalRoot: string, relativeRoot: string): QaSkillRoots;
+/** The directory of one skill, validated against the account's skills root. */
+export declare function skillDirectory(roots: QaSkillRoots, name: string): string;
+export declare function skillFilePath(roots: QaSkillRoots, name: string): string;
+/** Whether the directory exists at all, without following a symlink. */
+export declare function directoryExists(input: string): boolean;
+/**
+ * Materialize the skills root inside one account's personal root. Creation is
+ * followed by a re-canonicalization, so a directory that appeared as a link
+ * between the check and the `mkdir` is still refused.
+ */
+export declare function ensureSkillRoots(roots: QaSkillRoots): void;
+/** The skill subdirectories present for one account, sorted by name. */
+export declare function listSkillDirectories(roots: QaSkillRoots): readonly string[];
+//# sourceMappingURL=paths.d.ts.map

package/lib/types/personal-skills/provider.d.ts

@@ -0,0 +1,33 @@
+import type { SkillProvider, SkillProviderControl } from "@deepseek-ai/dsh-skill";
+import type { QaPersonalSkills } from "./service.js";
+/**
+ * Discovery provider for one QA account's own skills.
+ *
+ * It exists because the shipped filesystem provider resolves the project root
+ * through the nearest `.git`, which for a personal QA directory inside a larger
+ * checkout would climb above the account and mix users together. This provider
+ * reads exactly one place — `<cwd>/.dsh/skills` where the cwd is a provisioned
+ * `.qa-users/<uuid>` directory — and replaces the filesystem layer inside the
+ * QA scope rather than adding a second one beside it.
+ */
+export declare const QA_USER_SKILLS_PROVIDER = "qa-user-skills";
+/** Prompt-visible provenance label for a skill stored in an account directory. */
+export declare const QA_USER_SKILLS_SOURCE = "qa-user";
+/**
+ * Rank below the project layer (100) and the bundled layer (600): inside the
+ * QA scope a personal skill wins a same-named duplicate from any other layer.
+ */
+export declare const QA_USER_SKILLS_RANK = 50;
+/**
+ * Build the provider for one registration. The factory runs synchronously
+ * during `registerProvider` and all filesystem work stays inside
+ * `list`/`get`, which the registry calls per read.
+ *
+ * Note what the registry caches and what it does not: a loaded definition is
+ * never cached, so an edited body is visible to the next `get` immediately,
+ * while the candidate list behind a catalog summary is cached until something
+ * invalidates it. A save goes through the service, which invalidates; a file
+ * edited by hand is what the watcher exists for.
+ */
+export declare function createQaUserSkillProvider(control: SkillProviderControl, skills: QaPersonalSkills): SkillProvider;
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/personal-skills/remotes.d.ts

@@ -0,0 +1,35 @@
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaAccountRemotes } from "../account-remotes.js";
+import type { QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaPersonalSkills } from "./service.js";
+/**
+ * Host-side bodies of the personal-skill remotes. The `@Remote`-decorated
+ * signatures stay on the `QaSurface` service class (typert code generation
+ * reads the class shape); this context owns everything behind them: turning
+ * the wire's account token into the storage context, and mapping a refusal
+ * onto the shared `(reason: <code>)` marker the browser renders copy for.
+ *
+ * The browser never names a filesystem location. It names a skill; the account
+ * id behind the token decides where that name resolves.
+ */
+export interface QaPersonalSkillRemotes {
+    list(token: string): {
+        readonly skills: readonly QaSkillSummary[];
+    };
+    get(token: string, name: string): QaSkillDocument;
+    create(token: string, input: QaSkillDraftInput): QaSkillDocument;
+    update(token: string, name: string, input: QaSkillDraftInput): QaSkillDocument;
+    remove(token: string, name: string, expectedRevision: string | null): QaSkillRemoval;
+    validate(token: string, name: string | null, input: QaSkillDraftInput): QaSkillValidation;
+    tools(token: string): {
+        readonly tools: readonly QaSkillToolDescriptor[];
+    };
+    validate(token: string, name: string | null, input: QaSkillDraftInput): QaSkillValidation;
+}
+export declare function createQaPersonalSkillRemotes(options: {
+    getConfig: () => ResolvedQaSurfaceConfig;
+    logger: PluginLogger;
+    skills: QaPersonalSkills;
+    accounts: QaAccountRemotes;
+}): QaPersonalSkillRemotes;
+//# sourceMappingURL=remotes.d.ts.map

package/lib/types/personal-skills/service.d.ts

@@ -0,0 +1,131 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaSkillDiagnostic, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, ResolvedQaSurfaceConfig } from "../types.js";
+import { type QaSkillFileContents } from "./skill-file.js";
+/** Per-account identity of the skill storage boundary. */
+export interface QaPersonalSkillContext {
+    /** The authenticated account id whose personal root holds these skills. */
+    readonly userId: string;
+}
+/** One stored skill: its parsed contents plus the facts a DTO needs. */
+export interface QaStoredSkill {
+    /** Whether the skill directory itself exists. */
+    readonly exists: boolean;
+    /** Directory name; the skill's identity for every write. */
+    readonly directoryName: string;
+    readonly directory: string;
+    readonly filePath: string;
+    readonly raw: string;
+    readonly revision: string;
+    readonly updatedAt: string | null;
+    /** Absent when the file is missing or its frontmatter does not parse. */
+    readonly contents: QaSkillFileContents | undefined;
+    readonly diagnostics: readonly QaSkillDiagnostic[];
+    readonly resourceCount: number;
+}
+export interface QaPersonalSkillsOptions {
+    readonly getConfig: () => ResolvedQaSurfaceConfig;
+    readonly logger: PluginLogger;
+    /** The registered workspace path this deployment pins QA accounts under. */
+    readonly workspacePath: () => string | undefined;
+    /** Tells the DSH skill registry that a personal catalog may have changed. */
+    readonly invalidate: () => void;
+    /** Called once per storage root the discovery provider meets. */
+    readonly onRootDiscovered?: (root: string) => void;
+}
+/**
+ * Personal Skills over one account's own directory.
+ *
+ * The service is the only writer: it derives every path from the account id,
+ * validates a draft before touching the disk, writes `SKILL.md` through a
+ * temporary file and a rename, and keeps a removed skill recoverable in the
+ * trash beside its skills root. Reading is deliberately permissive — a skill
+ * whose file the parser rejects still returns a document carrying the
+ * diagnostic that says why, so the editor can repair it.
+ */
+export declare class QaPersonalSkills {
+    private readonly ctx;
+    private readonly options;
+    constructor(ctx: Context, options: QaPersonalSkillsOptions);
+    /** Whether the feature is available on this deployment at all. */
+    get enabled(): boolean;
+    /** Resolve one account's storage roots, or refuse the operation. */
+    private rootsFor;
+    /**
+     * Resolve the storage roots a session cwd names. This is the discovery
+     * provider's entry point and takes no account token: the cwd itself is the
+     * boundary, validated as a provisioned `<workspace>/.qa-users/<uuid>`
+     * directory, so no arbitrary directory can name another account's storage.
+     */
+    private rootsForCwd;
+    /** Every skill of one account, sorted by directory name. */
+    list(context: QaPersonalSkillContext): readonly QaSkillSummary[];
+    /** One skill with everything the editor needs. */
+    get(context: QaPersonalSkillContext, name: string): QaSkillDocument;
+    /**
+     * Check one unsaved draft without touching storage: the serializer is the
+     * one a Save uses and the preserved frontmatter is the stored file's, so the
+     * preview the editor shows is byte-for-byte the file that save would write,
+     * and the diagnostics carry the operator's own limit (which the browser
+     * cannot know). `name` is the stored skill being edited, or null to create.
+     */
+    validate(context: QaPersonalSkillContext, name: string | null, input: QaSkillDraftInput): QaSkillValidation;
+    /** Whether one account stores a skill under this name. */
+    has(context: QaPersonalSkillContext, name: string): boolean;
+    /** Create one skill directory and its `SKILL.md`. */
+    create(context: QaPersonalSkillContext, input: QaSkillDraftInput): QaSkillDocument;
+    /**
+     * Replace one skill's file, preserving the frontmatter fields this editor
+     * does not own and moving the whole directory when the name changed.
+     */
+    update(context: QaPersonalSkillContext, name: string, input: QaSkillDraftInput): QaSkillDocument;
+    /** Move one skill directory into the trash beside its skills root. */
+    remove(context: QaPersonalSkillContext, name: string, expectedRevision: string | null): QaSkillRemoval;
+    /**
+     * The tool catalog the picker offers. Availability is the QA session's own
+     * scope — the deployment's reviewed allow-list — never a suggestion of what
+     * a skill may grant: a declared tool the scope excludes stays listed and
+     * stays unavailable.
+     */
+    tools(context: QaPersonalSkillContext): readonly QaSkillToolDescriptor[];
+    /**
+     * The skills one session cwd exposes to DSH. A file the parser rejects, or
+     * one whose name disagrees with its directory, is reported in the editor and
+     * never handed to the model as a half-valid skill.
+     */
+    discover(cwd: string): readonly QaStoredSkill[];
+    /** Re-read one skill of a session cwd, re-checking the same boundary. */
+    read(cwd: string, directoryName: string): QaStoredSkill | undefined;
+    private observe;
+    private isDiscoverable;
+    private availableTools;
+    private declaredTools;
+    /** The foreign frontmatter a save must keep, read from the stored file. */
+    private storedFrontmatter;
+    /** Read one skill directory, tolerating every failure the editor must see. */
+    private load;
+    private resources;
+    /**
+     * Normalize one editor draft into the file to write. `strict` is the
+     * difference between a save and a check: a save refuses a draft the Host
+     * will not store, while a check hands the same problems back as diagnostics,
+     * because that is what the editor asked for.
+     */
+    private prepareWrite;
+    /** Move a renamed skill's whole directory, resources included. */
+    private renameSkillDirectory;
+    /** Write one file through a temporary sibling and a rename. */
+    private writeSkillFile;
+    private trashTarget;
+    private assertRevision;
+    private summarize;
+    private document;
+    private storageError;
+    /**
+     * Publish one write: audit it, then refresh the DSH catalog. The two are
+     * separate stages on purpose — a stored skill whose catalog refresh failed
+     * is still stored, and the deployment needs to see which half broke.
+     */
+    private refreshCatalog;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/personal-skills/skill-file.d.ts

@@ -0,0 +1,64 @@
+import type { QaSkillDiagnostic, QaSkillDiagnosticCode, QaSkillJsonValue } from "../types.js";
+/** The parsed shape of one skill file, without its generated diagnostics. */
+export interface QaSkillFileContents {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    readonly allowedTools: readonly string[];
+    /** Declared tool names dropped as unusable; reported, never silently kept. */
+    readonly rejectedTools: readonly string[];
+    /** Every frontmatter key the editor does not own, in document order. */
+    readonly extraFrontmatter: Readonly<Record<string, QaSkillJsonValue>>;
+    readonly body: string;
+    /** Non-blocking anomalies found while reading the file. */
+    readonly warnings: readonly QaSkillDiagnostic[];
+}
+/**
+ * A parse either yields contents or the single reason the file cannot become
+ * a skill. The blocking codes carry the upstream reason: `frontmatter-missing`
+ * covers both an absent block and a file that is nothing but a body.
+ */
+export type QaSkillFileParse = {
+    readonly ok: true;
+    readonly value: QaSkillFileContents;
+} | {
+    readonly ok: false;
+    readonly code: QaSkillDiagnosticCode;
+    readonly detail: string | null;
+};
+export interface QaSkillFileDraft {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    readonly allowedTools: readonly string[];
+    readonly extraFrontmatter: Readonly<Record<string, QaSkillJsonValue>>;
+    readonly body: string;
+}
+/**
+ * Coerce one YAML node to a JSON value, or undefined when JSON cannot carry
+ * it: preserved frontmatter crosses a JSON bridge, so what crosses it has to
+ * be exactly what a Save writes back.
+ */
+export declare function toJsonValue(value: unknown): QaSkillJsonValue | undefined;
+/** Parse one `SKILL.md` into its canonical shape plus read-time warnings. */
+export declare function parseSkillFile(raw: string): QaSkillFileParse;
+/**
+ * Write one `SKILL.md` from a draft. Known fields are emitted first in the
+ * canonical order every reader of this plugin sees; preserved foreign fields
+ * follow in the order they were read, so a skill authored elsewhere keeps its
+ * extra frontmatter across a Save in the editor.
+ */
+export declare function serializeSkillFile(draft: QaSkillFileDraft): string;
+/**
+ * The markdown body of a skill file, whether or not its frontmatter parses.
+ * A file the editor cannot open still has to show its instructions, so a
+ * malformed block yields the text below it and a file without a block yields
+ * itself.
+ */
+export declare function skillFileBody(raw: string): string;
+export * from "./skill-format.js";
+//# sourceMappingURL=skill-file.d.ts.map

package/lib/types/personal-skills/skill-format.d.ts

@@ -0,0 +1,100 @@
+import type { QaSkillDiagnostic, QaSkillDiagnosticCode } from "../types.js";
+/**
+ * The rules of the `SKILL.md` format that need no YAML: the name grammar, the
+ * declared-tool list, the draft limits, and where a personal root may sit.
+ *
+ * This module is deliberately free of Node builtins *and* of the YAML
+ * dependency, because the browser editor imports it: a YAML library ships a
+ * Node build beside its browser one, and the DSH module loader has no engine
+ * for the `require("process")` that build contains. The parser and serializer
+ * that do need YAML live in `skill-file.js`, which only the Host loads — the
+ * editor asks the Host for the file a draft would write and for the
+ * authoritative diagnostics, and shows its own answer immediately for the
+ * rules below.
+ */
+/** Name length cap; the upstream grammar itself is unbounded. */
+export declare const QA_SKILL_NAME_MAX = 64;
+export declare const QA_SKILL_DESCRIPTION_MAX = 1024;
+export declare const QA_SKILL_WHEN_TO_USE_MAX = 2048;
+/** One skill file's own ceiling, before any resource directory is considered. */
+export declare const QA_SKILL_FILE_MAX_BYTES: number;
+export declare const QA_SKILL_MAX_BYTES_MIN = 4096;
+export declare const QA_SKILL_MAX_BYTES_MAX: number;
+export declare const QA_SKILL_MAX_TOOLS = 256;
+/**
+ * Whether the feature is on for a deployment that could host it. The resolver
+ * still turns it off wherever accounts or per-account directories are absent:
+ * this is the operator's intent, not a capability.
+ */
+export declare const QA_SKILL_ENABLED_BY_DEFAULT = true;
+/** Where personal skills live below one account's own workspace directory. */
+export declare const QA_SKILL_DEFAULT_RELATIVE_ROOT = ".dsh/skills";
+export declare const QA_SKILL_RELATIVE_ROOT_MAX = 512;
+/** DSH's skill-name grammar: the registry refuses anything else outright. */
+export declare const QA_SKILL_NAME_PATTERN: RegExp;
+/** Frontmatter keys the editor owns. */
+export declare const KNOWN_SKILL_FIELDS: Set<string>;
+/**
+ * Agent Skills fields the editor preserves without offering a control for
+ * them. Anything outside both sets is still preserved; it only earns a
+ * warning that the deployment's editor does not know the field.
+ */
+export declare const PRESERVED_SKILL_FIELDS: Set<string>;
+/**
+ * Whether a configured `relativeRoot` may be resolved below a personal root.
+ * Only a relative, ordinary path qualifies: the value decides where the
+ * filesystem boundary of the feature sits, so an absolute path or one
+ * climbing out would move the boundary rather than relocate inside it.
+ */
+export declare function skillRelativeRootProblem(value: string): string | null;
+/** The directory segments of an already-validated relative root. */
+export declare function skillRelativeRootSegments(value: string): readonly string[];
+/** The reason a candidate name cannot be used, or null when it can. */
+export declare function skillNameProblem(value: string): "name-required" | "name-invalid" | null;
+export interface QaToolListNormalization {
+    readonly tools: readonly string[];
+    /** Entries that are not usable tool names; reported, never silently kept. */
+    readonly rejected: readonly string[];
+}
+/**
+ * Read a declared tool list. The canonical form is one space-separated
+ * scalar, but an array (and comma separators) are accepted for compatibility
+ * with skills authored elsewhere, and every form normalizes to the canonical
+ * deduplicated order.
+ */
+export declare function normalizeAllowedTools(value: unknown): QaToolListNormalization | undefined;
+export declare function skillWarning(code: QaSkillDiagnosticCode, field: string | null, detail: string | null): QaSkillDiagnostic;
+/** Byte length of the text a Save would write, in UTF-8. */
+export declare function skillFileBytes(text: string): number;
+export interface QaSkillValidationInput {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    readonly allowedTools: readonly string[];
+    /**
+     * Byte length of the serialized file. Omitted by a caller that cannot
+     * serialize — the browser editor — so the size rule stays on the Host,
+     * which knows both the operator's ceiling and the file it would write.
+     */
+    readonly sizeBytes?: number | undefined;
+    /** Operator-configured ceiling; the built-in default applies when omitted. */
+    readonly maxBytes?: number | undefined;
+    /**
+     * Names the current QA scope can actually use. Omitted when the catalog is
+     * unknown: a missing catalog must not turn every tool into a warning.
+     */
+    readonly availableTools?: readonly string[] | undefined;
+    /** Tool names submitted through the picker that are not usable names. */
+    readonly rejectedTools?: readonly string[] | undefined;
+    /** Frontmatter keys carried over from the file, for the unknown-field notice. */
+    readonly extraFieldNames?: readonly string[] | undefined;
+}
+/**
+ * Validate an editor draft. Every rule here is enforced again on the Host at
+ * write time; running it in the browser only makes the editor immediate, it is
+ * not the authority.
+ */
+export declare function validateSkillDraft(input: QaSkillValidationInput): readonly QaSkillDiagnostic[];
+//# sourceMappingURL=skill-format.d.ts.map

package/lib/types/personal-skills/watcher.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Follows personal skill directories so a file edited by hand — outside the
+ * editor — still reaches the DSH catalog without a restart.
+ *
+ * Registration is lazy and bounded: a root is watched the first time the
+ * discovery provider meets it, at most {@link QA_SKILL_WATCH_LIMIT} roots stay
+ * open (least recently used first), and every watcher is closed on dispose. A
+ * root that cannot be watched degrades to "no live refresh for that account":
+ * a save through the editor invalidates the registry directly and never
+ * depends on this path.
+ */
+export declare const QA_SKILL_WATCH_LIMIT = 16;
+export interface QaSkillWatcherOptions {
+    readonly onChange: () => void;
+    readonly onError: (message: string) => void;
+    readonly limit?: number;
+    readonly debounceMs?: number;
+}
+export declare class QaSkillWatcher {
+    private readonly options;
+    private readonly watchers;
+    private readonly limit;
+    private readonly debounceMs;
+    private timer;
+    constructor(options: QaSkillWatcherOptions);
+    /** How many roots are currently watched (tests and diagnostics). */
+    get size(): number;
+    /** Start following one skills root; idempotent per path. */
+    follow(root: string): void;
+    /** Stop following one root. */
+    close(root: string): void;
+    dispose(): void;
+    /**
+     * Coalesce a burst of filesystem events into one catalog refresh. The timer
+     * never holds the process open: a watcher must not keep the Host alive.
+     */
+    private schedule;
+}
+//# sourceMappingURL=watcher.d.ts.map

package/lib/types/profile.d.ts

@@ -24,6 +24,19 @@ 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;
+/**
+ * One single-line field: control characters out, whitespace runs collapsed to
+ * a space, trimmed to at most `maxLength` characters. Shared with the starter
+ * editor, whose button label obeys the same rules.
+ */
+export declare function cleanLine(value: unknown, maxLength: number): string;
+/**
+ * One multi-line field: line feeds survive (three or more collapse to a blank
+ * line), every other control character is dropped, and the result is trimmed
+ * to at most `maxLength` characters. Shared with the starter editor, whose
+ * sent prompt obeys the same rules.
+ */
+export declare function cleanBlock(value: unknown, maxLength: number): string;
 /**
  * Read one stored (or wire-delivered) profile into its public shape. Unknown
  * or hand-edited input degrades to the readable subset instead of throwing:

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

@@ -12,6 +12,8 @@ export declare const QA_NOTES_PLUGIN = "qa-surface";
 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";
+/** Note name asking the model to name its delegations. */
+export declare const QA_DELEGATION_NOTE = "dsh-qa-surface:delegation-naming";
 export interface QaIdentityRenderInput {
     /** The owner's account address; the one fact accounts always provide. */
     readonly email: string;
@@ -89,6 +91,13 @@ export declare class QaPromptNotes {
     private identityNotes;
     /** What the deployment expects around the sources the surface collects. */
     private sourcesNotes;
+    /**
+     * How the model should label its delegations: the host keeps the
+     * delegation's `description` as the child's durable creation label, and the
+     * surface shows it as the subagent's display name. A named delegation is
+     * the difference between a panel of hashes and a panel of tasks.
+     */
+    private delegationNotes;
     private carriedKey;
     /**
      * The text one note already carries in this agent's conversation. Process

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

@@ -1,10 +1,53 @@
 import type { QaSourceFilePreview } from "../types.js";
-export interface QaSourceFilePreviewOptions {
-    readonly root: string;
+/**
+ * Coarse, wire-safe preview refusal codes. They ride the shared
+ * `(reason: <code>)` marker, so the panel can tell "this file is not in a
+ * directory the QA read policy opens" from "this file is gone" instead of
+ * telling every audience that a present file moved away.
+ */
+export type QaSourcePreviewReason = "outside-roots" | "not-evidence" | "unavailable";
+/** Host refusal whose wire message carries the coarse reason marker. */
+export declare class QaSourcePreviewError extends Error {
+    readonly reason: QaSourcePreviewReason;
+    constructor(reason: QaSourcePreviewReason);
+}
+export interface QaSourceFilePreviewRequest {
     readonly sourcePath: string;
+    /**
+     * The attested chat's cwd. It is the root every relative source path in the
+     * evidence bundle was canonicalized against, and the anchor this read
+     * resolves a relative request against.
+     */
+    readonly cwd: string;
+    /**
+     * Whether one canonical path is evidence of the attested chat. The preview
+     * never browses: it opens exactly the files the bundle already recorded.
+     */
+    readonly isEvidence: (canonicalPath: string) => boolean;
+    /**
+     * Shared read directories of the deployment. The per-user execution guard
+     * already lets the model read these, so a source recorded from one of them
+     * must stay previewable.
+     */
+    readonly sharedReadOnlyRoots?: readonly string[];
+    /**
+     * The mounted attachment store. It sits outside every workspace on purpose,
+     * and the upload prompt points the model at the exact file an upload
+     * produced, so that one file is readable here too.
+     */
+    readonly attachmentRoot?: 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>;
+/**
+ * Read one evidence file from the roots the QA read policy opens.
+ *
+ * The bundle canonicalized each recorded path against the chat cwd, while the
+ * browser may hold either spelling of the same file: it projects sources with
+ * the *configured* session cwd, which is null whenever the chat is pinned by
+ * workspaceId or by an account directory. So the request is canonicalized the
+ * 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>;
 //# sourceMappingURL=file-preview.d.ts.map

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

@@ -1,4 +1,5 @@
 import type { Context } from "@deepseek-ai/cordis";
+import { type QaProvenanceSnapshotStore } from "./snapshot-store.js";
 import type { QaTurnSources } from "./types.js";
 import type { ResolvedQaSurfaceConfig } from "../types.js";
 export declare const QA_REPORT_SOURCES_TOOL = "qa_report_sources";
@@ -23,12 +24,15 @@ declare module "@deepseek-ai/cordis" {
 export declare class QaProvenanceHost {
     private readonly ctx;
     private readonly config;
+    private readonly store;
+    private readonly onPersistenceError;
     private readonly collectors;
     private readonly snapshots;
+    private readonly seededSessions;
     private readonly calls;
     private readonly lineage;
     private readonly disposers;
-    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig);
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, store?: QaProvenanceSnapshotStore, onPersistenceError?: (error: unknown) => void);
     dispose(): void;
     /**
      * Drop every per-session record of one chat. Long-lived servers outlive
@@ -49,6 +53,8 @@ export declare class QaProvenanceHost {
     private collector;
     private sessionCalls;
     private sessionSnapshots;
+    private hydrateStored;
+    private persistSnapshot;
 }
 export {};
 //# sourceMappingURL=host-store.d.ts.map

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

@@ -6,5 +6,6 @@ export * from "./file-preview.js";
 export * from "./host-store.js";
 export * from "./normalize.js";
 export * from "./reported.js";
+export * from "./snapshot-store.js";
 export type * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,23 @@
+import type { QaTurnSources } from "./types.js";
+export interface QaProvenanceSnapshotStore {
+    list(sessionId: string): readonly QaTurnSources[];
+    put(bundle: QaTurnSources): void;
+}
+/** Process-local store used by tests and explicit ephemeral deployments. */
+export declare class MemoryQaProvenanceSnapshotStore implements QaProvenanceSnapshotStore {
+    private readonly sessions;
+    list(sessionId: string): readonly QaTurnSources[];
+    put(bundle: QaTurnSources): void;
+}
+/** Default durable provenance path, deliberately outside Harness journals. */
+export declare function defaultQaProvenanceFilePath(): string;
+/** Atomically persists per-turn QA source snapshots in plugin-owned storage. */
+export declare class FileQaProvenanceSnapshotStore implements QaProvenanceSnapshotStore {
+    private readonly filePath;
+    constructor(filePath?: string);
+    list(sessionId: string): readonly QaTurnSources[];
+    put(bundle: QaTurnSources): void;
+    private load;
+    private persist;
+}
+//# sourceMappingURL=snapshot-store.d.ts.map

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

@@ -0,0 +1,29 @@
+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 QaToolActivationDetectorOptions {
+    readonly manager: QaToolActivationManager;
+    readonly logger: PluginLogger;
+    /** The exact skill name that unlocks the QA tools. */
+    readonly activationSkill: string;
+    /** Whether this agent's composition participates in QA tool activation. */
+    readonly isManagedAgent: (agent: Agent) => boolean;
+}
+/**
+ * Turns a successful QA skill load into an activation request.
+ *
+ * The trigger is the authoritative `tools/result` of the built-in `skill` tool,
+ * not the model's attempt and not the rendered conversation text: a refused,
+ * unknown, or cancelled skill load reaches this listener as an error result and
+ * activates nothing.
+ */
+export declare class QaToolActivationDetector {
+    private readonly ctx;
+    private readonly options;
+    private readonly dispose;
+    constructor(ctx: Context, options: QaToolActivationDetectorOptions);
+    private observe;
+    disposeListeners(): void;
+}
+//# sourceMappingURL=activation-detector.d.ts.map