@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

package/lib/types/documents/types.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Public types of the QA Surface document pipeline.
+ *
+ * The shapes here are the contract the agent sees (tool inputs and results),
+ * the contract the artifact store persists (manifest), and the contract the
+ * providers implement. They are deliberately free of any backend vocabulary:
+ * a tool result never names pandoc, LibreOffice or Docling, so a provider can
+ * be replaced without touching a prompt, a skill or a workflow
+ * (docs/specs/document-pipeline.md §4.1, §22).
+ */
+/** Formats the pipeline can read and write. */
+export type DocumentFormat = "md" | "docx" | "pdf";
+/** Formats a document can be created in. */
+export type CreateFormat = "docx" | "pdf";
+/** PDF production route (§14). */
+export type PdfMode = "office" | "typst" | "auto";
+/** Extraction quality/route selector (§9). */
+export type ExtractionMode = "auto" | "fast" | "accurate";
+/** OCR policy (§15.2). */
+export type OcrMode = "auto" | "off" | "force";
+/** Structural classification of an inspected input (§11). */
+export type DetectedFormat = "pdf" | "docx" | "docm" | "markdown" | "unknown";
+/** Stable warning codes; a warning never turns a success into a failure (§25). */
+export type DocumentWarningCode = "OCR_USED" | "TABLE_EXTRACTION_DEGRADED" | "UNSUPPORTED_EMBEDDED_OBJECT" | "FONT_SUBSTITUTED" | "IMAGE_SKIPPED" | "PAGE_LIMIT_REACHED" | "METADATA_PARTIALLY_EXTRACTED" | "BACKEND_FALLBACK_USED" | "FORMAT_FAILED" | "MARKDOWN_TRUNCATED" | "PAGE_SIZE_NOT_APPLIED" | "ASSET_MISSING" | "SOURCE_NOT_RETAINED" | "TEMPLATE_DEFAULTED";
+export interface DocumentWarning {
+    readonly code: DocumentWarningCode;
+    readonly message: string;
+    readonly backend?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/** One artifact file as reported to the agent. */
+export interface DocumentFileResult {
+    readonly format: CreateFormat | "md";
+    /** Absolute path, inside the session workspace. */
+    readonly path: string;
+    readonly mediaType: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly status: "created" | "failed";
+    /** Present when `status` is `failed`; the format's own error code. */
+    readonly error?: string;
+}
+export interface DocumentAssetInput {
+    readonly id: string;
+    /** Workspace-relative or absolute path inside the session scope. */
+    readonly path?: string;
+    /** Inline asset content: base64 data URI or raw base64. */
+    readonly dataRef?: string;
+    readonly filename?: string;
+    readonly mimeType?: string;
+}
+export interface DocumentCreateOptions {
+    readonly pdfMode?: PdfMode;
+    readonly pageSize?: string;
+    readonly locale?: string;
+    readonly toc?: boolean;
+    readonly preserveSource?: boolean;
+}
+export interface DocumentCreateInput {
+    readonly content: string;
+    readonly filename?: string;
+    readonly formats: readonly CreateFormat[];
+    readonly template?: string;
+    readonly title?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly assets?: readonly DocumentAssetInput[];
+    readonly options?: DocumentCreateOptions;
+}
+export interface DocumentCreateResult {
+    readonly artifactId: string;
+    readonly source?: {
+        readonly path: string;
+        readonly mediaType: "text/markdown";
+    };
+    readonly files: readonly DocumentFileResult[];
+    readonly template?: string;
+    readonly warnings: readonly DocumentWarning[];
+    readonly manifestPath: string;
+}
+export interface DocumentToMarkdownInput {
+    readonly file: string;
+    readonly mode?: ExtractionMode;
+    readonly ocr?: OcrMode;
+    readonly ocrLanguages?: readonly string[];
+    readonly extractImages?: boolean;
+    readonly extractTables?: boolean;
+    readonly preservePageMarkers?: boolean;
+    readonly outputFilename?: string;
+}
+export interface DocumentToMarkdownResult {
+    readonly artifactId: string;
+    /** Extracted Markdown; truncated to the configured inline budget. */
+    readonly markdown: string;
+    readonly markdownPath: string;
+    readonly assets?: readonly {
+        readonly path: string;
+        readonly mediaType: string;
+    }[];
+    readonly pages?: number;
+    readonly backend: string;
+    readonly warnings: readonly DocumentWarning[];
+    readonly manifestPath: string;
+}
+export interface DocumentConvertInput {
+    readonly file: string;
+    readonly targetFormat: CreateFormat | "md";
+    readonly template?: string;
+    readonly filename?: string;
+    /** Artifact name of the extracted Markdown when the target is `md`. */
+    readonly outputFilename?: string;
+    readonly options?: {
+        readonly pdfMode?: PdfMode;
+        readonly ocr?: OcrMode;
+    };
+}
+export interface DocumentConvertResult {
+    readonly artifactId: string;
+    readonly files: readonly DocumentFileResult[];
+    readonly source: {
+        readonly path: string;
+        readonly format: DocumentFormat;
+    };
+    readonly warnings: readonly DocumentWarning[];
+    readonly manifestPath: string;
+}
+export interface DocumentInspectInput {
+    readonly file: string;
+}
+export interface DocumentInspectResult {
+    readonly filename: string;
+    readonly format: DetectedFormat;
+    readonly mediaType: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly metadata?: {
+        readonly title?: string;
+        readonly author?: string;
+        readonly createdAt?: string;
+        readonly modifiedAt?: string;
+    };
+    readonly structure?: {
+        readonly pages?: number;
+        readonly headings?: number;
+        readonly tables?: number;
+        readonly images?: number;
+    };
+    readonly encrypted?: boolean;
+    readonly macroEnabled?: boolean;
+    readonly warnings: readonly DocumentWarning[];
+}
+/** Identifies the backend that produced one output, for the manifest (§19). */
+export interface BackendInfo {
+    readonly provider: string;
+    readonly version?: string;
+}
+/** Returned by providers that write a file. */
+export interface RenderedArtifact {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly backend: BackendInfo;
+    readonly warnings: readonly DocumentWarning[];
+}
+export interface RenderDocxInput {
+    readonly sourcePath: string;
+    readonly outputPath: string;
+    readonly workDir: string;
+    readonly assetsDir?: string;
+    /** Reference DOCX resolved from a template, when the template has one. */
+    readonly referenceDocPath?: string;
+    readonly templateName?: string;
+    readonly title?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly toc?: boolean;
+    readonly locale?: string;
+    readonly signal?: AbortSignal;
+}
+export interface RenderPdfInput {
+    readonly sourcePath: string;
+    readonly outputPath: string;
+    readonly workDir: string;
+    readonly assetsDir?: string;
+    readonly templateName?: string;
+    readonly typstTemplateDir?: string;
+    readonly pageSize?: string;
+    readonly title?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly toc?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface ExtractInput {
+    readonly inputPath: string;
+    readonly workDir: string;
+    /** Directory extracted images are written into, when extraction asks for them. */
+    readonly assetsDir: string;
+    readonly ocr: OcrMode;
+    readonly ocrLanguages?: readonly string[];
+    readonly extractImages: boolean;
+    readonly extractTables: boolean;
+    readonly preservePageMarkers: boolean;
+    readonly maxPages?: number;
+    readonly maxImages?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ExtractedDocument {
+    readonly markdown: string;
+    readonly assets: readonly {
+        readonly path: string;
+        readonly mediaType: string;
+    }[];
+    readonly pages?: number;
+    readonly backend: BackendInfo;
+    readonly warnings: readonly DocumentWarning[];
+}
+export interface ConvertPdfInput {
+    readonly inputPath: string;
+    readonly outputPath: string;
+    readonly workDir: string;
+    readonly signal?: AbortSignal;
+}
+export interface ConvertedDocument {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly backend: BackendInfo;
+    readonly warnings: readonly DocumentWarning[];
+}
+/** §22 provider interfaces. A tool never imports a concrete implementation. */
+export interface DocxRenderer {
+    readonly name: string;
+    render(input: RenderDocxInput): Promise<RenderedArtifact>;
+}
+export interface PdfRenderer {
+    readonly name: string;
+    render(input: RenderPdfInput): Promise<RenderedArtifact>;
+}
+export interface DocumentExtractor {
+    readonly name: string;
+    supports(format: DocumentFormat): boolean;
+    extract(input: ExtractInput): Promise<ExtractedDocument>;
+}
+export interface DocumentConverter {
+    readonly name: string;
+    supports(source: DocumentFormat, target: DocumentFormat): boolean;
+    convert(input: ConvertPdfInput): Promise<ConvertedDocument>;
+}
+/** Manifest document, written beside every artifact (§19). */
+export interface DocumentManifest {
+    readonly schemaVersion: 1;
+    readonly artifactId: string;
+    readonly operation: "document_create" | "document_to_markdown" | "document_convert";
+    readonly createdAt: string;
+    readonly input: {
+        readonly format: DocumentFormat | "unknown";
+        readonly sha256: string;
+        readonly filename?: string;
+        readonly bytes?: number;
+    };
+    readonly outputs: readonly {
+        readonly format: CreateFormat | "md";
+        readonly path: string;
+        readonly sha256: string;
+        readonly size: number;
+        readonly status: "created" | "failed";
+        readonly error?: string;
+    }[];
+    readonly template?: string;
+    readonly templateSha256?: string;
+    readonly backends: Readonly<Record<string, BackendInfo>>;
+    readonly warnings: readonly DocumentWarning[];
+    /** Authorization context (§40): what this artifact belongs to. */
+    readonly scope: {
+        readonly sessionId?: string;
+        readonly workspace?: string;
+    };
+}
+/** Backend availability, reported by capacity discovery and health (§42). */
+export type BackendStatus = "ok" | "unavailable" | "disabled";
+export interface DocumentHealth {
+    readonly status: "ok" | "degraded" | "unavailable";
+    readonly required: Readonly<Record<string, BackendStatus>>;
+    readonly optional: Readonly<Record<string, BackendStatus>>;
+}
+/** Capability discovery (§43). */
+export interface DocumentCapabilities {
+    readonly enabled: boolean;
+    readonly create: readonly CreateFormat[];
+    readonly extract: readonly DocumentFormat[];
+    readonly convert: readonly (readonly [DocumentFormat, DocumentFormat])[];
+    readonly ocr: boolean;
+    readonly templates: readonly string[];
+    readonly pdfModes: readonly PdfMode[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import type { Context } from "@deepseek-ai/cordis";
 import type { QaTurnSources } from "./provenance/types.js";
-import type { QaAccountProfileInput, QaAccountSession, QaAccountUserPublic, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSourceFilePreview, QaWhoamiResult } from "./types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaPrincipal } from "./types.js";
 export declare const name = "qa-surface";
 export declare const inject: string[];
 import { QA_SURFACE_SETTINGS_NAMESPACE } from "./shared/settings.js";
@@ -19,15 +19,38 @@ export declare class QaSurface extends TypertRemoteService {
     private source;
     private readonly logger;
     private readonly admission;
+    private readonly approvals;
+    private readonly userQuestions;
     private readonly provenance;
     private readonly notes;
+    /** Assigned after the admission gate; that gate only reads it per execution. */
+    private readonly tools;
     /** Account-remote bodies; the wire signatures stay on this class. */
     private readonly accountRemotes;
+    /** Personal skills: storage, the DSH provider and the manual-edit watcher. */
+    private readonly personalSkills;
+    /** Personal-skill remote bodies; the wire signatures stay on this class. */
+    private readonly skillRemotes;
     private readonly launchToken;
+    /** Root session principals attested for their owner, never for admin viewing. */
+    private readonly integrationPrincipals;
     private webServer;
     private disposeRoute;
     private routeKey;
+    /**
+     * The document subsystem: its own runtime and the four tool registrations.
+     * Rebuilt when the document configuration changes and torn down while the
+     * subsystem or the whole surface is disabled.
+     */
+    private documents;
+    private documentsKey;
     constructor(ctx: Context, entry?: QaSurfaceConfig);
+    /** Resolve browser authentication to the caller only; never accepts an id. */
+    principalForToken(token: string): QaPrincipal | undefined;
+    /** Resolve only a directly QA-owned root session; delegated children fail closed. */
+    principalForSession(sessionId: string): QaPrincipal | undefined;
+    /** Admit tools that independently enforce the same QA principal boundary. */
+    registerPrincipalScopedTools(names: readonly string[]): () => void;
     getConfig(): ResolvedQaSurfaceConfig;
     /**
      * Self-service signup; the first account ever created becomes admin. The
@@ -59,6 +82,12 @@ export declare class QaSurface extends TypertRemoteService {
      * store before anything is written.
      */
     accountsUpdateProfile(token: string, input: QaAccountProfileInput): QaAccountUserPublic;
+    /**
+     * Replace the caller's own starter buttons. Same self-service contract as
+     * the profile write: the token names the only editable account, and the
+     * deployment's limits are enforced in the store before anything is written.
+     */
+    accountsUpdateStarters(token: string, input: QaAccountStartersInput): QaAccountUserPublic;
     /**
      * Serve the effective QA configuration to the browser. The DSH gateway pins
      * settings RPCs to loopback, so a browser served over the LAN always sees
@@ -74,12 +103,79 @@ export declare class QaSurface extends TypertRemoteService {
      */
     createSession(token: string): Promise<string>;
     /** Pin and attest the effective policy. The browser supplies identity only. */
-    secureSession(token: string, sessionId: string): QaLockdownProof;
-    /** Return canonical Host snapshots; replay is rebuilt from qa/sources events. */
-    sources(token: string, sessionId: string): readonly QaTurnSources[];
-    /** Narrow read-only preview capability for files already present as sources. */
+    secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
+    /** Return canonical Host snapshots from plugin-owned durable provenance. */
+    sources(token: string, sessionId: string): Promise<readonly QaTurnSources[]>;
+    /**
+     * The tool calls of one chat that wait for the operator. Read-only: a
+     * deployment with blocked approvals answers with an empty list.
+     */
+    pendingApprovals(token: string, sessionId: string): Promise<readonly QaPendingApproval[]>;
+    /**
+     * Apply the operator's answer to one parked call. The id must belong to a
+     * request of this chat; an answer that lost the race (the turn was stopped,
+     * the agent went away) is refused with `false`.
+     */
+    answerApproval(token: string, sessionId: string, requestId: string, decision: QaApprovalDecision): Promise<boolean>;
+    /**
+     * The questions of one chat that wait for the operator. Read-only: a
+     * deployment with unsupported questions answers with an empty list.
+     */
+    pendingQuestions(token: string, sessionId: string): Promise<readonly QaPendingQuestion[]>;
+    /**
+     * Apply the operator's answers to one parked question request. Every question
+     * of the request must be present in `answers`; one the browser omits reads as
+     * a skip.
+     */
+    answerQuestion(token: string, sessionId: string, requestId: string, answers: readonly QaQuestionAnswerItem[]): Promise<boolean>;
+    /** Close a parked question request without answering it. */
+    cancelQuestion(token: string, sessionId: string, requestId: string): Promise<boolean>;
+    /**
+     * Narrow read-only preview capability for files already present as sources.
+     *
+     * The readable roots mirror the per-user execution guard: the chat's own cwd
+     * plus the deployment's shared read-only directories and the attachment
+     * store. Without that mirroring a source the model was explicitly allowed to
+     * read — the normal case for a deployment whose docs and code live beside
+     * the per-account scratch directory — could never be opened in the panel.
+     */
     readSourceFile(token: string, sessionId: string, sourcePath: string): Promise<QaSourceFilePreview>;
+    /** Every personal skill of the token's account, sorted by name. */
+    skillsList(token: string): {
+        readonly skills: readonly QaSkillSummary[];
+    };
+    /** One personal skill with the body, its preserved frontmatter and revision. */
+    skillsGet(token: string, name: string): QaSkillDocument;
+    /** Create one skill directory below the account's own workspace. */
+    skillsCreate(token: string, input: QaSkillDraftInput): QaSkillDocument;
+    /**
+     * Replace one skill. `expectedRevision` is the revision the editor read; a
+     * mismatch is refused rather than overwriting an edit made elsewhere.
+     */
+    skillsUpdate(token: string, name: string, input: QaSkillDraftInput): QaSkillDocument;
+    /** Remove one skill into the account's own trash directory. */
+    skillsRemove(token: string, name: string, expectedRevision: string | null): QaSkillRemoval;
+    /**
+     * Check an unsaved draft: the file a save would write and the diagnostics
+     * for it. `name` names the stored skill being edited, or null to create one.
+     */
+    skillsValidate(token: string, name: string | null, input: QaSkillDraftInput): QaSkillValidation;
+    /**
+     * The tool catalog the picker offers, with availability computed against
+     * this deployment's QA scope. Declaring a tool here never grants it.
+     */
+    skillsTools(token: string): {
+        readonly tools: readonly QaSkillToolDescriptor[];
+    };
     private refreshRoute;
+    /**
+     * Install, rebuild or tear down the document subsystem. The raw entry is
+     * resolved with the documented environment overrides applied, so a
+     * deployment can point `QA_DOCLING_BASE_URL` at its own service without
+     * touching the settings namespace; the settings layer stays authoritative
+     * for everything it declares.
+     */
+    private refreshDocuments;
 }
 export { ConfigSchema, DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath, resolveConfig, } from "./config.js";
 export { QaAttestationError } from "./attestation.js";
@@ -87,7 +183,9 @@ export type { QaAttestationReason } from "./attestation.js";
 export { QaAccounts, QaAccountsError } from "./accounts/store.js";
 export { entryRedirectRow, entryRedirectScript } from "./entry-redirect.js";
 export { registerQaNavigationRoute } from "./host-route.js";
+export { QaIntegrationPrincipalBindings } from "./integration-principals.js";
 export { qaToolDenial, qaToolPolicyPlan } from "./lockdown-policy.js";
+export * from "./documents/index.js";
 export { QaPolicyAdmission } from "./secure-session.js";
 export { QaPromptNotes, renderUserIdentity, QA_IDENTITY_NOTE, QA_SOURCES_NOTE, } from "./prompt-notes.js";
 export * from "./provenance/index.js";

package/lib/types/integration-principals.d.ts

@@ -0,0 +1,9 @@
+import type { QaPrincipal } from "./types.js";
+/** Runtime-only proof that a QA root session was attested by its own user. */
+export declare class QaIntegrationPrincipalBindings {
+    private readonly principals;
+    attest(sessionId: string, actorUserId: string | undefined, ownerUserId: string | undefined): void;
+    resolve(sessionId: string, currentOwnerUserId: string | undefined): QaPrincipal | undefined;
+    clear(): void;
+}
+//# sourceMappingURL=integration-principals.d.ts.map

package/lib/types/lockdown-policy.d.ts

@@ -13,6 +13,16 @@ export interface QaToolPolicyPlan {
  * successful first attestation and make the next attestation fail.
  */
 export declare function qaToolPolicyPlan(allow: readonly string[], isMounted: (toolName: string) => boolean): QaToolPolicyPlan;
-/** Monotonic execution decision shared by inherited, scoped and transport tools. */
-export declare function qaToolDenial(allowed: ReadonlySet<string>, toolName: string): string | undefined;
+/**
+ * Monotonic execution decision shared by inherited, scoped and transport tools.
+ * @param allowed - the operator's configured allow-list for this agent.
+ * @param toolName - the tool the model is trying to call.
+ * @param dynamicNames - names this plugin attached for the calling agent after
+ *   a successful skill load. They are deliberately absent from the allow-list:
+ *   that list is validated against the mounted catalog at attestation time, and
+ *   a tool that appears only later cannot be named there without failing the
+ *   check. The guard is therefore where they are authorized — a dynamic tool
+ *   stays as unchecked as any allow-listed one, and no less.
+ */
+export declare function qaToolDenial(allowed: ReadonlySet<string>, toolName: string, dynamicNames?: readonly string[]): string | undefined;
 //# sourceMappingURL=lockdown-policy.d.ts.map

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

@@ -0,0 +1,11 @@
+/**
+ * Coarse, wire-safe personal-skill failure codes. They ride the same
+ * `(reason: <code>)` marker the account remotes established: the browser maps
+ * them to audience-safe copy, while the precise cause stays in the Host log.
+ */
+export type QaPersonalSkillErrorReason = "skills-disabled" | "workspace-unavailable" | "skill-not-found" | "skill-exists" | "skill-conflict" | "skill-name-invalid" | "skill-invalid" | "storage-unavailable";
+export declare class QaPersonalSkillError extends Error {
+    readonly reason: QaPersonalSkillErrorReason;
+    constructor(reason: QaPersonalSkillErrorReason, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1,42 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+import { QaPersonalSkills } from "./service.js";
+export interface QaPersonalSkillsHostOptions {
+    readonly ctx: Context;
+    readonly getConfig: () => ResolvedQaSurfaceConfig;
+    readonly logger: PluginLogger;
+}
+/**
+ * Host owner of the personal-skills feature: the storage service, the DSH
+ * provider registration and the manual-edit watcher.
+ *
+ * The three are one unit because they share a single liveness contract — every
+ * write through the service, and every filesystem event the watcher observes,
+ * invalidates the same provider registration, so the catalog the model reads
+ * and the catalog the editor writes cannot drift apart. The provider is
+ * registered through `ctx.inject`, so a deployment without the skills service
+ * keeps the editor working and simply publishes nothing to DSH.
+ */
+export declare class QaPersonalSkillsHost {
+    readonly service: QaPersonalSkills;
+    private readonly watcher;
+    private readonly options;
+    /**
+     * The registry's own invalidation callback, guarded by registration
+     * identity on its side: a reference kept past disposal is a no-op.
+     */
+    private invalidateCatalog;
+    private disposeRegistration;
+    constructor(options: QaPersonalSkillsHostOptions);
+    /** Whether the DSH registry currently owns this deployment's provider. */
+    get registered(): boolean;
+    dispose(): void;
+    /**
+     * The registered workspace path the per-account directories live under.
+     * Resolved per call: a deployment may register the workspace after this
+     * plugin loads.
+     */
+    private registeredWorkspacePath;
+}
+//# sourceMappingURL=host.d.ts.map

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

@@ -0,0 +1,10 @@
+export { QaPersonalSkillError, type QaPersonalSkillErrorReason, } from "./errors.js";
+export { QA_SKILL_TRASH_SUFFIX, resolveSkillRoots, skillDirectory, skillFilePath, type QaSkillRoots, } from "./paths.js";
+export { normalizeAllowedTools, parseSkillFile, serializeSkillFile, skillFileBody, skillNameProblem, toJsonValue, type QaSkillFileContents, type QaSkillFileDraft, type QaSkillFileParse, } from "./skill-file.js";
+export { skillFileBytes, skillRelativeRootProblem, skillRelativeRootSegments, validateSkillDraft, QA_SKILL_DEFAULT_RELATIVE_ROOT, QA_SKILL_DESCRIPTION_MAX, QA_SKILL_ENABLED_BY_DEFAULT, QA_SKILL_FILE_MAX_BYTES, QA_SKILL_MAX_BYTES_MAX, QA_SKILL_MAX_BYTES_MIN, QA_SKILL_MAX_TOOLS, QA_SKILL_NAME_MAX, QA_SKILL_NAME_PATTERN, QA_SKILL_WHEN_TO_USE_MAX, type QaSkillValidationInput, } from "./skill-format.js";
+export { QA_USER_SKILLS_PROVIDER, QA_USER_SKILLS_RANK, QA_USER_SKILLS_SOURCE, createQaUserSkillProvider, } from "./provider.js";
+export { QaPersonalSkills, type QaPersonalSkillContext, type QaPersonalSkillsOptions, type QaStoredSkill, } from "./service.js";
+export { createQaPersonalSkillRemotes, type QaPersonalSkillRemotes, } from "./remotes.js";
+export { QaPersonalSkillsHost } from "./host.js";
+export { QaSkillWatcher } from "./watcher.js";
+//# sourceMappingURL=index.d.ts.map

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