@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

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/reported.d.ts

@@ -1,5 +1,13 @@
 import { canonicalizeUrl } from "./normalize.js";
 import type { QaReportedSource, QaSourceOrigin, QaSourceReference } from "./types.js";
+export interface ReportedSourceOptions {
+    /**
+     * Whether a reported source must carry an address to be recorded. With
+     * `false`, a source the model wrote without a usable path or URL keeps its
+     * own type, title and snippet instead of being dropped.
+     */
+    readonly validate?: boolean;
+}
 /** 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;
+export declare function normalizeReportedSource(source: QaReportedSource, origin: QaSourceOrigin, workspaceRoot?: string, urlOptions?: Parameters<typeof canonicalizeUrl>[1], options?: ReportedSourceOptions): QaSourceReference | null;
 //# sourceMappingURL=reported.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

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