@yadsh/dsh-qa-surface 0.5.0 → 0.6.0

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

@@ -0,0 +1,33 @@
+/**
+ * The four agent-facing document tools (§8–§11, §34) and their registration.
+ *
+ * Registration is explicit and returns its disposers: the host may register
+ * them globally (the default) or an agent scope may register the same
+ * definitions later, which is what a deployment that wants progressive
+ * disclosure needs. Nothing here decides *whether* document tools are visible;
+ * that is the deployment's allow-list.
+ */
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type { DocumentRuntime } from "../runtime.js";
+import { DOCUMENT_CONVERT_TOOL } from "./convert.js";
+import { DOCUMENT_CREATE_TOOL } from "./create.js";
+import { DOCUMENT_INSPECT_TOOL } from "./inspect.js";
+import { DOCUMENT_TO_MARKDOWN_TOOL } from "./to-markdown.js";
+/** Exact names of the tools this subsystem registers (allow-list contract). */
+export declare const DOCUMENT_TOOL_NAMES: readonly string[];
+export { DOCUMENT_CONVERT_TOOL, DOCUMENT_CREATE_TOOL, DOCUMENT_INSPECT_TOOL, DOCUMENT_TO_MARKDOWN_TOOL, };
+export declare function createDocumentTools(options: {
+    readonly runtime: DocumentRuntime;
+}): ToolDefinition[];
+/** Anything that can accept a tool definition; the host's registry facade. */
+export interface DocumentToolRegistry {
+    register(definition: ToolDefinition): () => void;
+}
+/**
+ * Register every document tool and return one disposer. `enabled: false` is
+ * handled by the caller: the surface is then absent rather than inert.
+ */
+export declare function registerDocumentTools(registry: DocumentToolRegistry, options: {
+    readonly runtime: DocumentRuntime;
+}): () => void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * `document_inspect` — what a document is, without converting it (§11, §34).
+ */
+import type { DocumentRuntime } from "../runtime.js";
+export declare const DOCUMENT_INSPECT_TOOL = "document_inspect";
+export declare function createDocumentInspectTool(options: {
+    readonly runtime: DocumentRuntime;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=inspect.d.ts.map

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

@@ -0,0 +1,77 @@
+/**
+ * What the four document tools share: the calling session's scope, the output
+ * shapes they render, and the warning formatter.
+ *
+ * A tool is a thin adapter. It reads the session's working directory (the
+ * artifact root and the allowed input roots both derive from it), hands intent
+ * to the runtime, and renders the structured result for the model. No tool
+ * knows a backend name beyond the one the result reports.
+ */
+import type { ParameterSchemaSpec } from "@deepseek-ai/dsh-tools";
+import type { DocumentScope } from "../orchestrator/scope.js";
+import type { DocumentFileResult, DocumentWarning } from "../types.js";
+/**
+ * Model-facing shape of a warning. The tool results carry code, message and
+ * backend; the diagnostic `details` stay in the manifest, where they are read
+ * by an operator rather than by the model.
+ */
+export interface ToolWarning {
+    readonly code: string;
+    readonly message: string;
+    readonly backend?: string;
+}
+export declare function toolWarnings(warnings: readonly DocumentWarning[]): ToolWarning[];
+/** Shared output-schema fragment for the `warnings` array of every tool. */
+export declare const warningsSchema: {
+    type: "array";
+    items: {
+        type: "object";
+        additionalProperties: false;
+        properties: {
+            code: {
+                type: "string";
+                required: true;
+            };
+            message: {
+                type: "string";
+                required: true;
+            };
+            backend: {
+                type: "string";
+            };
+        };
+    };
+};
+/** Mutable projection of a produced file for the tool result. */
+export declare function toolFiles(files: readonly DocumentFileResult[]): {
+    format: string;
+    path: string;
+    mediaType: string;
+    size: number;
+    sha256: string;
+    status: string;
+    error?: string;
+}[];
+/** Structural view of the execution context a tool body needs. */
+export interface DocumentToolExec {
+    readonly signal?: AbortSignal;
+    readonly agent?: {
+        readonly session: {
+            readonly header: {
+                readonly cwd?: string;
+                readonly id?: unknown;
+            };
+        };
+    };
+}
+/**
+ * Resolve the session scope, failing closed: a session without a working
+ * directory gets no document access rather than the host process's cwd.
+ */ export declare function requireDocumentScope(exec: DocumentToolExec): DocumentScope;
+export declare function fileParameter(): ParameterSchemaSpec[string];
+export declare function formatBytes(bytes: number): string;
+export declare function renderWarning(warning: ToolWarning): string;
+/** One line per produced file, plus failed formats explicitly named. */
+export declare function renderFiles(files: readonly DocumentFileResult[]): string[];
+export declare const ARTIFACT_NOTE = "The artifact directory keeps the source, the assets and manifest.json beside the outputs.";
+//# sourceMappingURL=shared.d.ts.map

package/lib/types/documents/tools/to-markdown.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `document_to_markdown` — DOCX/PDF to Markdown (§9, §34).
+ *
+ * The model gets the extracted text and a path to the full copy; the artifact
+ * bundle keeps the input, the extracted Markdown and any extracted images.
+ */
+import type { DocumentRuntime } from "../runtime.js";
+export declare const DOCUMENT_TO_MARKDOWN_TOOL = "document_to_markdown";
+export declare function createDocumentToMarkdownTool(options: {
+    readonly runtime: DocumentRuntime;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=to-markdown.d.ts.map

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, QaApprovalDecision, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, 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";
@@ -23,13 +23,34 @@ export declare class QaSurface extends TypertRemoteService {
     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
@@ -61,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
@@ -77,7 +104,7 @@ 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): Promise<QaLockdownProof>;
-    /** Return canonical Host snapshots; replay is rebuilt from qa/sources events. */
+    /** 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
@@ -103,9 +130,52 @@ export declare class QaSurface extends TypertRemoteService {
     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. */
+    /**
+     * 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";
@@ -113,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