@yadsh/dsh-qa-surface 0.6.1 → 0.7.1

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

@@ -1,14 +0,0 @@
-/**
- * `document_create` — Markdown to DOCX and/or PDF (§8, §34).
- *
- * This is the tool the agent reaches for instead of driving pandoc and
- * LibreOffice itself, which is the whole point of the pipeline: the intent is
- * "give me this report as a Word file and a PDF", and the service decides how
- * that happens.
- */
-import type { DocumentRuntime } from "../runtime.js";
-export declare const DOCUMENT_CREATE_TOOL = "document_create";
-export declare function createDocumentCreateTool(options: {
-    readonly runtime: DocumentRuntime;
-}): import("@deepseek-ai/dsh-tools").ToolDefinition;
-//# sourceMappingURL=create.d.ts.map

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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,9 +0,0 @@
-/**
- * `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

@@ -1,77 +0,0 @@
-/**
- * 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

@@ -1,12 +0,0 @@
-/**
- * `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

@@ -1,294 +0,0 @@
-/**
- * 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