@xiaoso/dsh-tool-plus 0.1.7-beta.0 → 0.1.7

package/lib/types/tools/omp/utils/cpuprofile.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Parser and renderer for V8 `.cpuprofile` files (emitted by `node --cpu-prof`,
+ * `bun --cpu-prof`, Chrome DevTools, and the CDP `Profiler` domain).
+ *
+ * The raw file is a JSON blob with a flat node table and up to millions of
+ * sample/timestamp entries — useless to read directly. `renderCpuProfile`
+ * converts it into a compact bottleneck summary:
+ *
+ * - the hot-path call tree, pruned to frames with meaningful self time,
+ *   with pass-through chains collapsed and direct recursion flattened
+ * - `(idle)` time excluded from on-CPU totals
+ * - a profile-wide "top functions by self time" table
+ *
+ * Consumed by the read tool: `*.cpuprofile` reads show the summary, `:raw`
+ * returns the original JSON.
+ */
+/** Matches paths the read tool should treat as V8 CPU profiles. */
+export declare function isCpuProfilePath(filePath: string): boolean;
+/** Call-site metadata of one profile node. `lineNumber` is 0-based. */
+export interface CpuProfileCallFrame {
+    functionName: string;
+    url?: string;
+    lineNumber?: number;
+}
+/** One node in the flat profile tree; `children` are node ids. */
+export interface CpuProfileNode {
+    id: number;
+    callFrame: CpuProfileCallFrame;
+    hitCount?: number;
+    children?: number[];
+}
+/** Parsed V8 CPU profile. `startTime`/`endTime`/`timeDeltas` are microseconds. */
+export interface CpuProfile {
+    nodes: CpuProfileNode[];
+    startTime: number;
+    endTime: number;
+    samples?: number[];
+    timeDeltas?: number[];
+}
+/**
+ * Parse a `.cpuprofile` JSON blob. Accepts both the bare profile and the CDP
+ * `Profiler.stop` result shape (`{ profile: {...} }`). Returns null when the
+ * text is not a structurally valid V8 CPU profile.
+ */
+export declare function parseCpuProfile(text: string): CpuProfile | null;
+/**
+ * Render a V8 CPU profile as an agent-friendly bottleneck summary.
+ * Returns null when `text` is not a CPU profile (caller falls back to the
+ * plain-text path).
+ */
+export declare function renderCpuProfile(text: string): string | null;

package/lib/types/tools/omp/utils/edit-mode.d.ts

@@ -0,0 +1,13 @@
+export type EditMode = "replace" | "patch" | "hashline" | "apply_patch";
+export declare const DEFAULT_EDIT_MODE: EditMode;
+export declare const EDIT_MODES: EditMode[];
+export declare function normalizeEditMode(mode?: string | null): EditMode | undefined;
+export interface EditModeSettingsLike {
+    get(key: "edit.mode"): unknown;
+    getEditVariantForModel?(model: string | undefined): EditMode | null;
+}
+export interface EditModeSessionLike {
+    settings: EditModeSettingsLike;
+    getActiveModelString?: () => string | undefined;
+}
+export declare function resolveEditMode(session: EditModeSessionLike): EditMode;

package/lib/types/tools/omp/utils/file-display-mode.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve line-display mode for file-like outputs (read, grep, @file mentions).
+ */
+export interface FileDisplayMode {
+    lineNumbers: boolean;
+    hashLines: boolean;
+}
+/** Session-like object providing settings and tool availability for display mode resolution. */
+export interface FileDisplayModeSession {
+    /** Whether the edit tool is available. Hashlines are suppressed without it. */
+    hasEditTool?: boolean;
+    settings: {
+        get(key: "readLineNumbers" | "edit.mode"): unknown;
+    };
+}
+/**
+ * Computes effective line display mode from session settings/env.
+ * Hashline mode takes precedence and implies line-addressed output everywhere.
+ * Hashlines are suppressed when the edit tool is not available (e.g. scout agents),
+ * when the caller signals a `raw` read, and when the source is `immutable`
+ * (e.g. internal URLs like artifact://, agent://, memory:// — there is no edit
+ * path that could consume the anchors). Raw output is returned as-is.
+ */
+export declare function resolveFileDisplayMode(session: FileDisplayModeSession, options?: {
+    raw?: boolean;
+    immutable?: boolean;
+}): FileDisplayMode;

package/lib/types/tools/omp/utils/image-loading.d.ts

@@ -0,0 +1,51 @@
+import type { ImageContent, Model } from "@oh-my-pi/pi-ai";
+import { type ImageResizeOptions } from "./image-resize";
+/**
+ * Ollama and its local-backend family decode image input through llama.cpp /
+ * `stb_image`, which is compiled without WebP support, so a WebP upload fails
+ * with an opaque HTTP 400. Detect those models so the resize pipeline encodes
+ * to PNG/JPEG instead — the automatic equivalent of `OMP_NO_WEBP=1`.
+ */
+export declare function modelLacksWebpSupport(model: Pick<Model, "provider" | "api" | "imageInputDecoder"> | undefined): boolean;
+/**
+ * `true` when `model` cannot decode WebP, otherwise `undefined` so the
+ * `OMP_NO_WEBP` env fallback in {@link resizeImage} still applies. Feed straight
+ * into {@link ImageResizeOptions.excludeWebP}.
+ */
+export declare function webpExclusionForModel(model: Pick<Model, "provider" | "api"> | undefined): true | undefined;
+export declare const MAX_IMAGE_INPUT_BYTES: number;
+export declare const SUPPORTED_INPUT_IMAGE_MIME_TYPES: Set<string>;
+export interface LoadImageInputOptions {
+    path: string;
+    cwd: string;
+    autoResize: boolean;
+    maxBytes?: number;
+    resolvedPath?: string;
+    detectedMimeType?: string;
+    /** Force non-WebP output (e.g. for Ollama). Leave unset to honor `OMP_NO_WEBP`. */
+    excludeWebP?: boolean;
+    /**
+     * DSH extension (拍板#22 config expansion): resize-knob passthrough onto
+     * {@link resizeImage}. Upstream never passes these — it relies on the
+     * hardcoded 1568px/500KB/200px/quality-80 defaults; the tool-plus config
+     * panel wires user-tunable values through here. Unset = upstream behavior.
+     */
+    resize?: ImageResizeOptions;
+}
+export interface LoadedImageInput {
+    resolvedPath: string;
+    mimeType: string;
+    data: string;
+    textNote: string;
+    dimensionNote?: string;
+    bytes: number;
+}
+export declare class ImageInputTooLargeError extends Error {
+    readonly bytes: number;
+    readonly maxBytes: number;
+    constructor(bytes: number, maxBytes: number);
+}
+/** Converts an image to PNG, rejecting when the runtime cannot decode or encode it. */
+export declare function convertImageToPng(image: ImageContent): Promise<ImageContent>;
+export declare function ensureSupportedImageInput(image: ImageContent): Promise<ImageContent | null>;
+export declare function loadImageInput(options: LoadImageInputOptions): Promise<LoadedImageInput | null>;

package/lib/types/tools/omp/utils/image-resize.d.ts

@@ -0,0 +1,42 @@
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+export interface ImageResizeOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Smallest allowed edge length (px). Inputs below this are scaled up. */
+    minDimension?: number;
+    maxBytes?: number;
+    jpegQuality?: number;
+    excludeWebP?: boolean;
+}
+export interface ResizedImage {
+    buffer: Uint8Array;
+    mimeType: string;
+    originalWidth: number;
+    originalHeight: number;
+    width: number;
+    height: number;
+    wasResized: boolean;
+    decodeFailed?: boolean;
+    get data(): string;
+}
+/**
+ * Resize and recompress an image to fit within the specified max dimensions and file size.
+ *
+ * Strategy:
+ *  1. Probe metadata. If already within all limits, return original.
+ *  2. Resize to fit max dimensions and encode at high quality across PNG/JPEG (+ WebP) — return smallest.
+ *  3. If still too large, walk a lossy JPEG/WebP quality ladder.
+ *  4. If still too large, walk a dimension-scale ladder × quality ladder.
+ *  5. If still too large, return the smallest variant produced.
+ *
+ * Set OMP_NO_WEBP to exclude WebP from encoding (llama.cpp STB doesn't decode it).
+ *
+ * Backed by `Bun.Image`: a chainable native pipeline that runs decode/transform/encode
+ * off the JS thread when the terminal (`.bytes()`) is awaited.
+ */
+export declare function resizeImage(img: ImageContent, options?: ImageResizeOptions): Promise<ResizedImage>;
+/**
+ * Format a dimension note for resized images.
+ * This helps the model understand the coordinate mapping.
+ */
+export declare function formatDimensionNote(result: ResizedImage): string | undefined;

package/lib/types/tools/omp/utils/lang-from-path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Language id for syntax highlighting and UI (icons, read tool), or undefined if unknown.
+ */
+export declare function getLanguageFromPath(filePath: string): string | undefined;
+export declare function isMarkdownPath(filePath: string): boolean;
+/**
+ * LSP language identifier; falls back to `plaintext`.
+ */
+export declare function detectLanguageId(filePath: string): string;

package/lib/types/tools/omp/utils/markit-cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cache schema/format revision. Bumping it changes the on-disk key prefix
+ * (`v<N>-...`), so old entries become unreachable and are pruned naturally.
+ * Bump when the cache *file* shape changes (entry JSON layout, key scheme).
+ *
+ * Converter *output* changes are handled separately: the package version is
+ * folded into the key (see {@link markitConversionCacheKey}), so any release
+ * that ships new markdown from `src/markit/converters/*` auto-invalidates the
+ * cache without a manual bump here.
+ */
+export declare const MARKIT_CONVERSION_CACHE_VERSION = 1;
+export declare const MAX_MARKIT_CONVERSION_CACHE_BYTES: number;
+export type MarkitConversionCacheStatus = "hit" | "miss" | "skipped";
+export type MarkitConversionCacheReadResult = {
+    status: "hit";
+    content: string;
+} | {
+    status: "miss";
+};
+export declare function markitConversionCacheKey(bytes: Uint8Array, extension: string): string;
+export declare function readMarkitConversionCache(key: string): Promise<MarkitConversionCacheReadResult>;
+export declare function pruneMarkitConversionCache(cacheDir: string): Promise<void>;
+export declare function writeMarkitConversionCache(key: string, content: string): Promise<void>;

package/lib/types/tools/omp/utils/markit.d.ts

@@ -0,0 +1,30 @@
+import { type MarkitConversionCacheStatus } from "./markit-cache";
+/**
+ * File extensions markit can actually convert to markdown — one per registered
+ * converter in `src/markit/registry.ts` (pdf, docx, pptx, xlsx, epub). This is
+ * the single source of truth shared by the read, fetch, and CLI file tools so
+ * the advertised set never drifts from the converters that back it. Legacy
+ * binary formats (`.doc`, `.ppt`, `.xls`, `.rtf`) are intentionally absent:
+ * markit has no converter for them, so routing them here only produced an
+ * `Unsupported format` error instead of letting them fall through to the
+ * binary-file handling.
+ */
+export declare const CONVERTIBLE_EXTENSIONS: ReadonlySet<string>;
+export interface MarkitConversionResult {
+    content: string;
+    ok: boolean;
+    error?: string;
+    cache?: MarkitConversionCacheStatus;
+}
+export interface MarkitFileConversionOptions {
+    /**
+     * Directory converters may use for extracted image or diagram files. Since
+     * those files are conversion side effects, conversions using this option
+     * bypass the markdown cache.
+     */
+    imageDir?: string;
+}
+export declare function convertFileWithMarkit(filePath: string, signal?: AbortSignal, options?: MarkitFileConversionOptions): Promise<MarkitConversionResult>;
+export declare function convertBufferWithMarkit(buffer: Uint8Array, extension: string, signal?: AbortSignal, options?: {
+    useCache?: boolean;
+}): Promise<MarkitConversionResult>;

package/lib/types/tools/omp/utils/profile-tree.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared display-tree machinery for profile summaries (macOS `sample` reports,
+ * V8 `.cpuprofile` files). Callers build {@link ProfileNode} trees with a
+ * domain-specific metric (on-CPU samples, self microseconds, …); this module
+ * merges same-key siblings, flattens direct recursion, collapses pass-through
+ * chains, and renders the pruned hot-path tree.
+ */
+/** Display node: merged, recursion-flattened mirror of a profile subtree. */
+export interface ProfileNode {
+    /** Merge/recursion identity (demangled symbol, function@call-site, …). */
+    key: string;
+    /** Human-readable label; recursion and truncation decorations are applied at render time. */
+    label: string;
+    /** Inclusive metric for this subtree (on-CPU samples, self µs, …); drives pruning and display. */
+    value: number;
+    /** Levels of direct recursion flattened into this node. */
+    recursion: number;
+    children: ProfileNode[];
+}
+/** Merge `b` into `a` (same key), combining values and child lists. */
+export declare function mergeInto(a: ProfileNode, b: ProfileNode): void;
+/**
+ * Flatten direct recursion: children carrying the node's own key are dissolved
+ * into it (their children promoted and merged), so a 15-deep recursive spine
+ * renders as one annotated node.
+ */
+export declare function flattenRecursion(node: ProfileNode): void;
+/** `n` as a percentage of `total`, one decimal (`"12.3%"`); `"0%"` when total is empty. */
+export declare function formatPct(n: number, total: number): string;
+/** Options for {@link renderProfileNode}. */
+export interface RenderTreeContext {
+    out: string[];
+    /** Denominator for percentage annotations. */
+    total: number;
+    /** Minimum subtree value a child needs to stay visible. */
+    minValue: number;
+    /** Format a metric value for the left column. */
+    formatValue: (value: number) => string;
+    /** Left-column width (characters) for formatted values. */
+    valueWidth: number;
+}
+/**
+ * Render one hot-path subtree: pass-through chains (single kept child, no own
+ * contribution above `minValue`) collapse into a single `a › b › c` line, and
+ * children below `minValue` are pruned.
+ */
+export declare function renderProfileNode(node: ProfileNode, indent: number, ctx: RenderTreeContext): void;

package/lib/types/tools/omp/utils/sample-profile.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Parser and renderer for macOS `/usr/bin/sample` call-tree reports
+ * (conventionally saved as `*.sample.txt`).
+ *
+ * The raw report is a 10k+ line ASCII call tree with mangled symbols —
+ * expensive for an agent to digest. `renderSampleProfile` converts it into a
+ * compact bottleneck summary:
+ *
+ * - per-thread hot paths, pruned to frames with meaningful on-CPU samples,
+ *   with pass-through chains collapsed and direct recursion flattened
+ * - blocked/idle threads reduced to a one-line classification
+ * - a process-wide "top functions by self samples" table
+ * - Rust v0 and legacy symbols demangled (best-effort, path extraction)
+ *
+ * Consumed by the read tool: `*.sample.txt` reads show the summary, `:raw`
+ * returns the original bytes.
+ */
+/** Matches paths the read tool should treat as macOS sample reports. */
+export declare function isSampleProfilePath(filePath: string): boolean;
+/** One frame in the sampled call tree. Counts are sample hits (subtree total). */
+export interface SampleFrame {
+    count: number;
+    symbol: string;
+    module?: string;
+    children: SampleFrame[];
+}
+/** One sampled thread: `Thread_<id>` root plus its call tree. */
+export interface SampleThread {
+    id: string;
+    name?: string;
+    total: number;
+    roots: SampleFrame[];
+}
+/** Metadata from the report preamble (everything before `Call graph:`). */
+export interface SampleProfileHeader {
+    process: string;
+    pid: number;
+    intervalMs: number;
+    path?: string;
+    codeType?: string;
+    osVersion?: string;
+    footprint?: string;
+    footprintPeak?: string;
+}
+/** Parsed macOS sample report. */
+export interface SampleProfile {
+    header: SampleProfileHeader;
+    threads: SampleThread[];
+}
+/**
+ * Parse a macOS `sample` report. Returns null when the text does not look
+ * like sample output (missing analysis preamble or `Call graph:` section).
+ */
+export declare function parseSampleProfile(text: string): SampleProfile | null;
+/**
+ * Best-effort demangle of Rust symbols (v0 `_R…` and legacy `_ZN…E`).
+ * For v0 this is a path extractor, not a full demangler: identifiers are
+ * pulled out in order and joined with `::`, so generic arguments appear as
+ * extra path segments. Non-Rust symbols pass through unchanged.
+ */
+export declare function demangleSymbol(raw: string): string;
+/**
+ * Render a macOS sample report as an agent-friendly bottleneck summary.
+ * Returns null when `text` is not sample output (caller falls back to the
+ * plain-text path).
+ */
+export declare function renderSampleProfile(text: string): string | null;

package/lib/types/tools/omp/utils/sixel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns whether SIXEL passthrough is explicitly enabled.
+ *
+ * Both gates must be enabled to preserve SIXEL control sequences:
+ * - PI_FORCE_IMAGE_PROTOCOL=sixel
+ * - PI_ALLOW_SIXEL_PASSTHROUGH=1
+ */
+export declare function isSixelPassthroughEnabled(): boolean;
+/** Returns true when the text contains a SIXEL start sequence. */
+export declare function containsSixelSequence(text: string): boolean;
+/**
+ * Returns a boolean mask indicating which lines belong to a SIXEL sequence block.
+ * Supports multi-line SIXEL payloads generated by libsixel.
+ */
+export declare function getSixelLineMask(lines: string[]): boolean[];
+/** Returns true when the line contains a SIXEL start sequence. */
+export declare function isSixelLine(line: string): boolean;
+/**
+ * Sanitizes text while preserving embedded SIXEL sequences when passthrough is enabled.
+ */
+export declare function sanitizeWithOptionalSixelPassthrough(text: string, sanitize: (text: string) => string): string;

package/lib/types/tools/omp/utils/tools-manager.d.ts

@@ -0,0 +1,11 @@
+export type ToolName = "sd" | "sg" | "yt-dlp" | "trafilatura";
+export declare function getToolPath(tool: ToolName): string | null;
+/** Download a tool asset without handing the streaming Response to Bun.write. */
+export declare function downloadFile(url: string, dest: string, signal?: AbortSignal): Promise<void>;
+type EnsureToolOptions = {
+    signal?: AbortSignal;
+    silent?: boolean;
+    notify?: (message: string) => void;
+};
+export declare function ensureTool(tool: ToolName, silentOrOptions?: EnsureToolOptions): Promise<string | undefined>;
+export {};

package/lib/types/tools/omp/utils/turndown.d.ts

@@ -0,0 +1,15 @@
+import TurndownService from "@oh-my-pi/pi-utils/turndown";
+/**
+ * Build a Turndown instance configured for GFM with the fixes omp relies on:
+ * `~~strikethrough~~`, unescaped heading periods, and single-space list markers.
+ *
+ * Shared by the web scrapers (HTML → markdown) and the markit document engine
+ * (`src/markit`). The rule set must stay identical across both call sites.
+ */
+export declare function createTurndown(): TurndownService;
+/**
+ * Normalize HTML tables so turndown-plugin-gfm can render them:
+ * - strip `<p>` tags inside `<td>`/`<th>` cells (joining paragraphs with a space)
+ * - wrap the first row in `<thead>` when missing
+ */
+export declare function normalizeTablesHtml(html: string): string;

package/lib/types/tools/omp/utils/zip.d.ts

@@ -0,0 +1,129 @@
+/** A ZIP archive decoded to a `path → bytes` map of its file members. */
+export type Unzipped = Record<string, Uint8Array>;
+/** Read a single ZIP entry as UTF-8 text, or `undefined` when the entry is absent. */
+export declare function unzipText(entries: Unzipped, entryPath: string): string | undefined;
+/**
+ * Decode an in-memory ZIP archive into a `path → bytes` map of its file members
+ * (directory entries and `..`-escaping names are dropped). Shares the
+ * central-directory record parser with the lazy, file-backed reader.
+ */
+export declare function unzip(bytes: Uint8Array): Unzipped;
+export type ArchiveFormat = "zip" | "tar" | "tar.gz";
+/**
+ * Where to read an archive from: an extension-inferred filesystem path, a
+ * format-tagged filesystem path, or in-memory bytes with an explicit format.
+ * ZIP paths are read lazily via ranged central-directory access.
+ */
+export type ArchiveSource = string | {
+    bytes: Uint8Array;
+    format: ArchiveFormat;
+} | {
+    path: string;
+    format: ArchiveFormat;
+};
+/** Content for a member when packing or extracting an archive. */
+export type ArchiveMemberContent = string | Uint8Array | Blob;
+export interface ArchivePathCandidate {
+    archivePath: string;
+    subPath: string;
+}
+export interface ArchiveNode {
+    path: string;
+    isDirectory: boolean;
+    size: number;
+    mtimeMs?: number;
+}
+export interface ArchiveDirectoryEntry extends ArchiveNode {
+    name: string;
+}
+export interface ExtractedArchiveFile extends ArchiveNode {
+    bytes: Uint8Array;
+}
+/** A byte window into an archive — file-backed (lazy) or in-memory. */
+interface ByteSource {
+    readonly size: number;
+    read(start: number, end: number): Promise<Uint8Array>;
+}
+interface TarStorage {
+    type: "tar";
+    buffer: Uint8Array;
+    dataOffset: number;
+    sparse: boolean;
+}
+interface TarLinkStorage {
+    type: "tar-link";
+    targetPath: string;
+}
+interface ZipStorage {
+    type: "zip";
+    source: ByteSource;
+    compressedSize: number;
+    compression: number;
+    flags: number;
+    localHeaderOffset: number;
+}
+type EntryStorage = TarStorage | TarLinkStorage | ZipStorage;
+interface ArchiveIndexEntry extends ArchiveNode {
+    storage?: EntryStorage;
+}
+/** Infer an archive format from a filesystem path's extension. */
+export declare function archiveFormatFromPath(filePath: string): ArchiveFormat | undefined;
+export declare function formatArchiveEntryLines(entries: readonly ArchiveDirectoryEntry[]): string[];
+export declare function sniffArchiveFormat(bytes: Uint8Array): ArchiveFormat | undefined;
+/**
+ * Split an `archive.ext:inner/path` reference into every plausible
+ * `{ archivePath, subPath }` pair, longest archive prefix first. A path may
+ * contain more than one archive extension, so each candidate is a guess at
+ * where the archive ends and the member portion begins.
+ */
+export declare function parseArchivePathCandidates(filePath: string): ArchivePathCandidate[];
+/**
+ * An indexed, read-only view over a single archive. ZIP archives are indexed
+ * from the central directory and members are inflated on demand; tar archives
+ * are parsed from one in-memory buffer, members are sliced on demand, and
+ * directory symlink aliases are traversed lazily.
+ */
+export declare class ArchiveReader {
+    #private;
+    readonly format: ArchiveFormat;
+    constructor(format: ArchiveFormat, entries: ArchiveIndexEntry[]);
+    getNode(subPath?: string): ArchiveNode | undefined;
+    listDirectory(subPath?: string): ArchiveDirectoryEntry[];
+    readFile(subPath: string): Promise<ExtractedArchiveFile>;
+}
+/**
+ * Open an archive for reading. ZIP archives opened from a path are indexed
+ * lazily via ranged central-directory reads (members inflate on demand); tar
+ * archives and in-memory ZIPs are read from a single buffer.
+ */
+export declare function openArchive(source: ArchiveSource): Promise<ArchiveReader>;
+/** Render the top-level entries of an in-memory archive as one line each. */
+export declare function listArchiveRoot(bytes: Uint8Array, format: ArchiveFormat, opts?: {
+    limit?: number;
+}): Promise<string>;
+/**
+ * Fully materialize every file member into a `path → content` map: ZIP members
+ * are inflated in memory, tar members are sliced from the decoded archive
+ * buffer. Use this when you need every entry (rewrite, extract); for browsing
+ * or single-member reads prefer `openArchive`, which is lazy for ZIP.
+ */
+export declare function readArchiveEntries(source: ArchiveSource): Promise<Map<string, ArchiveMemberContent>>;
+/**
+ * Serialize `entries` into an archive of `format` and write it to `destPath`.
+ * ZIP is framed in memory, tar / tar.gz via `Bun.Archive` (gzip for tar.gz).
+ * String members are encoded as UTF-8.
+ */
+export declare function writeArchive(destPath: string, format: ArchiveFormat, entries: Iterable<readonly [string, ArchiveMemberContent]>): Promise<void>;
+/**
+ * Extract every file member to `destDir`, creating parent directories as
+ * needed. Entries that would escape `destDir` (via `..` or an absolute path)
+ * are rejected. Returns the number of files written.
+ */
+export declare function extractArchive(source: ArchiveSource, destDir: string): Promise<number>;
+/**
+ * Frame a `path → bytes` map into a ZIP archive in memory. Each member is raw
+ * DEFLATE unless that would not shrink it, in which case it is stored. ZIP64 is
+ * not emitted; archives beyond the 32-bit limits throw rather than corrupt.
+ */
+export declare function zip(entries: Unzipped): Uint8Array;
+export {};

package/lib/types/tools/omp/web/browser-render.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Browser JS rendering for the read URL pipeline — the last reader backend
+ * in `FETCH_PROVIDER_ORDER`. Where the other backends fetch the raw HTML and
+ * convert it server-side, this one launches a real headless Chromium
+ * (puppeteer-core), lets the page's JavaScript run, and extracts readable
+ * content from the rendered DOM — which is what SPA pages need.
+ *
+ * Design (per the 2026-08-29 plan):
+ * - Singleton browser: lazily launched on first use, reused across renders,
+ *   closed after `BROWSER_IDLE_CLOSE_MS` of inactivity, best-effort killed on
+ *   process exit; a memoized instance found closed (idle recycle / crash) is
+ *   cleared and relaunched on the next render. A promise queue serializes
+ *   renders (one page at a time).
+ * - Budget: goto ≤ min(overall timeout, 20s), `domcontentloaded` + 800ms JS
+ *   settle, DOM capped at `BROWSER_RENDER_MAX_BYTES` before extraction.
+ * - Failure degenerates to `null` (the fetch chain then moves to the next
+ *   backend or reports the raw HTML), never throws for "no browser".
+ *
+ * `resetBrowserForTests` is the test seam for the unit suite.
+ * @module @xiaoso/dsh-tool-plus/web/browser-render
+ */
+/** Cap on the rendered DOM handed to the readable extractor. */
+export declare const BROWSER_RENDER_MAX_BYTES: number;
+/** Idle time after which the singleton browser is closed (renders reuse it). */
+export declare const BROWSER_IDLE_CLOSE_MS = 60000;
+/** Extra settle time after `domcontentloaded` for JS-rendered content. */
+export declare const RENDER_SETTLE_MS = 800;
+/**
+ * Render a URL in a headless browser and return readable markdown, or null
+ * when no browser is available / rendering fails. Serialized through the
+ * singleton queue; honors `signal` cancellation between attempts.
+ */
+export declare function renderUrlWithBrowser(url: string, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<string | null>;
+/**
+ * Test seam: replicate the production idle-close state — the singleton
+ * browser is closed but `browserPromise` is left pointing at the dead
+ * instance (which is exactly what {@link scheduleIdleClose} does). A render
+ * in this state must relaunch rather than fail.
+ */
+export declare function simulateIdleCloseForTests(): Promise<void>;
+/**
+ * Test seam: close the singleton browser (if any) and reset the queue so a
+ * later render starts from a clean state. Also clears the launch memo so a
+ * subsequent render re-resolves the executable (e.g. after the detection
+ * RPC ran).
+ */
+export declare function resetBrowserForTests(): Promise<void>;

package/lib/types/tools/omp/web/parallel.d.ts

@@ -0,0 +1,68 @@
+import { type FetchImpl } from "@oh-my-pi/pi-ai";
+import type { AgentStorage } from "../session/agent-storage";
+export declare const PARALLEL_SEARCH_URL = "https://api.parallel.ai/v1beta/search";
+export declare const PARALLEL_BETA_HEADER = "search-extract-2025-10-10";
+export interface ParallelUsageItem {
+    name?: string;
+    count?: number;
+}
+export interface ParallelSearchSource {
+    title: string;
+    url: string;
+    snippet?: string;
+    publishedDate?: string;
+    excerpts: string[];
+}
+export interface ParallelSearchResult {
+    requestId: string;
+    sources: ParallelSearchSource[];
+    warnings: string[];
+    usage: ParallelUsageItem[];
+}
+export interface ParallelExtractDocument {
+    url: string;
+    title?: string;
+    publishedDate?: string;
+    excerpts: string[];
+    fullContent?: string;
+}
+export interface ParallelExtractErrorEntry {
+    url: string;
+    errorType?: string;
+    httpStatusCode?: number;
+    content?: string;
+}
+export interface ParallelExtractResult {
+    requestId: string;
+    results: ParallelExtractDocument[];
+    errors: ParallelExtractErrorEntry[];
+    warnings: string[];
+    usage: ParallelUsageItem[];
+}
+export interface ParallelSearchOptions {
+    mode?: "fast" | "research";
+    maxCharsPerResult?: number;
+    signal?: AbortSignal;
+    fetch?: FetchImpl;
+}
+export interface ParallelExtractOptions {
+    objective?: string;
+    searchQueries?: string[];
+    excerpts?: boolean;
+    fullContent?: boolean;
+    signal?: AbortSignal;
+    fetch?: FetchImpl;
+}
+export declare class ParallelApiError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+export declare function parseParallelErrorResponse(statusCode: number, responseText: string): ParallelApiError;
+export declare function parseParallelJsonResponse(response: Response, operation: "search" | "extract"): Promise<unknown>;
+export declare function parseParallelSearchPayload(payload: unknown, options?: {
+    parseMetadata?: boolean;
+}): ParallelSearchResult;
+export declare function findParallelApiKey(storage: AgentStorage | null | undefined): string | null;
+export declare function getParallelExtractContent(document: ParallelExtractDocument): string;
+export declare function searchWithParallel(objective: string, queries: string[], options: ParallelSearchOptions, storage: AgentStorage | null | undefined): Promise<ParallelSearchResult>;
+export declare function extractWithParallel(urls: string[], options: ParallelExtractOptions, storage: AgentStorage | null | undefined): Promise<ParallelExtractResult>;