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

package/lib/types/tools/omp/task/spawn-policy.d.ts

@@ -0,0 +1,22 @@
+/** Default agent used when a session has unrestricted spawning. */
+export declare const DEFAULT_SPAWN_AGENT = "task";
+/** Spawn policy derived from a parent agent's `spawns` frontmatter. */
+export interface ResolvedSpawnPolicy {
+    /** True when at least one subagent may be spawned. */
+    enabled: boolean;
+    /** Agent used when the caller omits the agent field. */
+    defaultAgent: string;
+    /** Explicitly allowed agents, or `null` when the policy is unrestricted. */
+    allowedAgents: readonly string[] | null;
+    /** Text used in spawn rejection messages. */
+    allowedErrorText: string;
+    /** Backtick-quoted explicit agents for prompt descriptions. */
+    allowedPromptText?: string;
+}
+/** Resolves spawn frontmatter into the default and prompt/error surfaces. */
+export declare function resolveSpawnPolicy(parentSpawns: string | boolean | null | undefined): ResolvedSpawnPolicy;
+/**
+ * Whether the `scout` agent is spawnable in a session: not disabled via
+ * `task.disabledAgents`, and permitted by the session spawn policy.
+ */
+export declare function isScoutSpawnable(disabledAgents: readonly string[] | undefined, spawns: string | boolean | null | undefined): boolean;

package/lib/types/tools/omp/tools/approval.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool approval resolution.
+ *
+ * Approval policy is declared by each tool. This module only knows how to:
+ * - normalize user `tools.approval.<tool>: allow | deny | prompt` overrides,
+ * - compare a tool capability tier against the active approval mode,
+ * - format the generic approval prompt body.
+ */
+import type { AgentTool, ToolTier } from "@oh-my-pi/pi-agent-core";
+export type { ToolApproval, ToolApprovalDecision, ToolTier } from "@oh-my-pi/pi-agent-core";
+export type ApprovalPolicy = "allow" | "deny" | "prompt";
+export type ApprovalMode = "always-ask" | "write" | "yolo";
+type ApprovalSubject = Pick<AgentTool, "name" | "approval" | "formatApprovalDetails">;
+export interface ResolvedApproval {
+    policy: ApprovalPolicy;
+    tier: ToolTier;
+    reason?: string;
+    override: boolean;
+    source?: "tool" | "user" | "mode";
+    /** User-policy key that produced `source: "user"` (defaults to the tool name). */
+    policyKey?: string;
+}
+/**
+ * Evaluate a tool's own approval declaration against `args` and return the
+ * resulting capability tier, defaulting to `exec` when the tool omits an
+ * approval. Unlike reading `tool.approval` directly, this runs function-valued
+ * approvals — the write tool's `xd://` gate uses it to take a mounted device's
+ * argument-dependent tier instead of falling back to `exec`.
+ */
+export declare function resolveToolTier(tool: ApprovalSubject, args: unknown): ToolTier;
+/**
+ * Resolve approval policy for a tool call.
+ *
+ * Resolution order:
+ *  1. Tool `approval(args)` decision, defaulting to tier "exec" when omitted.
+ *     A decision may carry a `policyKey` — `tools.approval.<policyKey>` is then
+ *     the user override consulted instead of `tools.approval.<tool.name>`, with
+ *     the invoking tool's own policy as the fallback when the user set none for
+ *     the keyed sub-tool (e.g. an `xd://` device dispatch without a device
+ *     policy still honors `tools.approval.write`).
+ *  2. User per-tool override, if set and valid.
+ *  3. Active mode tier comparison.
+ *
+ * In yolo mode, override-based tool prompts are ignored; user `tools.approval`
+ * settings remain authoritative.
+ */
+export declare function resolveApproval(tool: ApprovalSubject, args: unknown, mode: ApprovalMode, userConfig?: Record<string, unknown>): ResolvedApproval;
+/**
+ * Check if a tool call requires user approval.
+ *
+ * @throws Error if policy is 'deny'
+ * @returns Object with required flag and optional reason for the prompt
+ */
+export declare function requiresApproval(tool: ApprovalSubject, args: unknown, mode: ApprovalMode, userConfig?: Record<string, unknown>): {
+    required: boolean;
+    reason?: string;
+};
+export declare function truncateForPrompt(value: string, maxChars?: number): string;
+/**
+ * Format the approval prompt body shown to the user.
+ */
+export declare function formatApprovalPrompt(tool: ApprovalSubject, args: unknown, reason?: string): string;

package/lib/types/tools/omp/tools/ast-edit.d.ts

@@ -0,0 +1,73 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
+import type { ToolSession } from "../sdk";
+import type { OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const astEditSchema: import("@oh-my-pi/omptype").FluentType<{
+    paths: string[];
+    ops: {
+        out: string;
+        pat: string;
+    }[];
+}, {
+    paths: string[];
+    ops: {
+        out: string;
+        pat: string;
+    }[];
+}>;
+export interface AstEditToolDetails {
+    totalReplacements: number;
+    filesTouched: number;
+    filesSearched: number;
+    applied: boolean;
+    limitReached: boolean;
+    parseErrors?: string[];
+    /** Total parse error count before {@link PARSE_ERRORS_LIMIT} capping. Omitted when no errors. */
+    parseErrorsTotal?: number;
+    scopePath?: string;
+    files?: string[];
+    fileReplacements?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter (no model-only hashline anchors). The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+    /** Absolute base directory used during the edit. Used by the renderer to resolve
+     * display-relative paths to absolute paths for OSC 8 hyperlinks. */
+    searchPath?: string;
+    /** Session cwd at edit time. Display header paths are cwd-relative, so the
+     * renderer resolves them against this; `searchPath` is the scope target. */
+    cwd?: string;
+}
+type AstEditSchemaInfer = typeof astEditSchema.infer;
+export declare class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolDetails> {
+    private readonly session;
+    readonly name = "ast_edit";
+    readonly approval: (args: unknown) => "read" | "write";
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    readonly label = "AST Edit";
+    readonly summary = "Perform AST-aware code edits (structural refactoring)";
+    readonly description: string;
+    readonly parameters: import("@oh-my-pi/omptype").FluentType<{
+        paths: string[];
+        ops: {
+            out: string;
+            pat: string;
+        }[];
+    }, {
+        paths: string[];
+        ops: {
+            out: string;
+            pat: string;
+        }[];
+    }>;
+    readonly strict = true;
+    readonly examples: readonly ToolExample<AstEditSchemaInfer>[];
+    readonly deferrable = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: AstEditSchemaInfer, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AstEditToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<AstEditToolDetails>>;
+}
+export {};

package/lib/types/tools/omp/tools/ast-grep.d.ts

@@ -0,0 +1,61 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
+import type { ToolSession } from "../sdk";
+import type { OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const astGrepSchema: import("@oh-my-pi/omptype").FluentType<{
+    pat: string;
+    path?: string | undefined;
+    skip?: number | undefined;
+}, {
+    pat: string;
+    path?: string | undefined;
+    skip?: number | undefined;
+}>;
+export interface AstGrepToolDetails {
+    matchCount: number;
+    fileCount: number;
+    filesSearched: number;
+    limitReached: boolean;
+    parseErrors?: string[];
+    /** Total parse error count before {@link PARSE_ERRORS_LIMIT} capping. Omitted when no errors. */
+    parseErrorsTotal?: number;
+    scopePath?: string;
+    files?: string[];
+    fileMatches?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter and `*` to mark match lines. The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+    /** Absolute base directory used during search. Used by the renderer to resolve
+     * display-relative paths to absolute paths for OSC 8 hyperlinks. */
+    searchPath?: string;
+    /** Session cwd at search time. Display header/match paths are cwd-relative, so
+     * the renderer resolves them against this; `searchPath` is the scope target. */
+    cwd?: string;
+}
+export declare class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolDetails> {
+    private readonly session;
+    readonly name = "ast_grep";
+    readonly approval: "read";
+    readonly label = "AST Grep";
+    readonly summary = "Search code with AST patterns (structural grep)";
+    get description(): string;
+    readonly parameters: import("@oh-my-pi/omptype").FluentType<{
+        pat: string;
+        path?: string | undefined;
+        skip?: number | undefined;
+    }, {
+        pat: string;
+        path?: string | undefined;
+        skip?: number | undefined;
+    }>;
+    readonly strict = true;
+    readonly examples: readonly ToolExample<typeof astGrepSchema.inferIn>[];
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: typeof astGrepSchema.infer, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AstGrepToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<AstGrepToolDetails>>;
+}
+export {};

package/lib/types/tools/omp/tools/auto-generated-guard.d.ts

@@ -0,0 +1,20 @@
+import { type Settings } from "../config/settings.ts";
+/**
+ * Check if a file is auto-generated by examining its content.
+ * Throws ToolError if the file appears to be auto-generated.
+ *
+ * @param absolutePath - Absolute path to the file
+ * @param displayPath - Path to show in error messages (relative or as provided)
+ * @param activeSettings - Session settings; falls back to global settings or the schema default
+ */
+export declare function assertEditableFile(absolutePath: string, displayPath?: string, activeSettings?: Settings): Promise<void>;
+/**
+ * Check if file content is auto-generated.
+ * Uses only the first CHECK_BYTE_COUNT characters of the content.
+ * Throws ToolError if the content appears to be auto-generated.
+ *
+ * @param content - File content to check (can be full content or prefix)
+ * @param displayPath - Path to show in error messages
+ * @param activeSettings - Session settings; falls back to global settings or the schema default
+ */
+export declare function assertEditableFileContent(content: string, displayPath: string, activeSettings?: Settings): void;

package/lib/types/tools/omp/tools/conflict-detect.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Detect and resolve unresolved git merge conflicts that surface in `read`
+ * output.
+ *
+ * Workflow:
+ *   1. `read` collects lines from disk as usual.
+ *   2. `scanConflictLines` inspects those lines (no extra I/O) for
+ *      well-formed `<<<<<<<` / `=======` / `>>>>>>>` blocks.
+ *   3. Each completed block is registered with the session's
+ *      `ConflictHistory`, which assigns it a stable id.
+ *   4. The read output is returned verbatim with a short footer naming
+ *      every conflict id surfaced, and the agent calls
+ *      `write({ path: "conflict://<id>", content })` to splice the
+ *      recorded region with the chosen content.
+ *
+ * Marker shape is strict: only column-0 markers of the exact prefix length
+ * followed by either EOL or a single space + label count. Lines that
+ * merely start with `<` or `=` never match.
+ */
+import type { ToolSession } from "./index";
+export interface ConflictBlock {
+    /** 1-indexed line of the `<<<<<<<` marker. */
+    startLine: number;
+    /** 1-indexed line of the `=======` separator. */
+    separatorLine: number;
+    /** 1-indexed line of the `>>>>>>>` marker. */
+    endLine: number;
+    /** 1-indexed line of the `|||||||` base marker (diff3 only). */
+    baseLine?: number;
+    oursLabel?: string;
+    baseLabel?: string;
+    theirsLabel?: string;
+    oursLines: string[];
+    baseLines?: string[];
+    theirsLines: string[];
+}
+/**
+ * Scan an already-collected array of file lines for completed conflict
+ * blocks. `firstLineNumber` is the 1-indexed line number of `lines[0]`
+ * (so a windowed read starting at line 200 passes `firstLineNumber: 200`).
+ *
+ * Only fully-closed blocks (opener + separator + closer all present in
+ * the window) are returned. A block whose closer is past the window's
+ * tail is dropped — the agent will see the open marker and can widen
+ * the read.
+ */
+export declare function scanConflictLines(lines: readonly string[], firstLineNumber: number): ConflictBlock[];
+/**
+ * Scan a whole file for unresolved conflict blocks.
+ *
+ * Reads at most `maxBytes` (default 10 MB) so this stays cheap on
+ * pathological files. Files truncated by the cap report
+ * `scanTruncated: true`; only complete blocks within the scanned prefix
+ * are returned, so trailing partial markers never invent fake blocks.
+ */
+export declare function scanFileForConflicts(absolutePath: string, options?: {
+    maxBytes?: number;
+}): Promise<{
+    blocks: ConflictBlock[];
+    scanTruncated: boolean;
+}>;
+/**
+ * Recorded conflict block keyed by a session-stable id. The history is
+ * append-only; ids stay valid even after later writes resolve other
+ * blocks in the same file, so retries don't depend on re-reading.
+ */
+export interface ConflictEntry extends ConflictBlock {
+    id: number;
+    absolutePath: string;
+    displayPath: string;
+}
+/** Per-session log of conflict regions surfaced by `read`. */
+export declare class ConflictHistory {
+    #private;
+    /**
+     * Register a conflict block. Returns the (possibly pre-existing) entry
+     * — if the same `absolutePath`+`startLine` was registered before, the
+     * earlier id is reused so a re-read does not inflate the counter or
+     * orphan the prior id. The recorded region is overwritten on re-read
+     * so the splice always reflects the current marker positions on disk.
+     */
+    register(input: Omit<ConflictEntry, "id">): ConflictEntry;
+    get(id: number): ConflictEntry | undefined;
+    /** Snapshot every registered entry in insertion (id) order. */
+    entries(): ConflictEntry[];
+    /** Drop a single entry by id. Used after a successful resolve. */
+    invalidate(id: number): void;
+    /** Drop every entry referencing `absolutePath`. Used after a successful resolve. */
+    invalidatePath(absolutePath: string): void;
+}
+/** Lazily attach a `ConflictHistory` to the session and return it. */
+export declare function getConflictHistory(session: ToolSession): ConflictHistory;
+/** A side of a conflict block that the `read` tool can render via `conflict://N/<scope>`. */
+export type ConflictScope = "ours" | "theirs" | "base";
+/** Parsed `conflict://<N>` / `conflict://<N>/<scope>` / `conflict://*` URI. */
+export interface ParsedConflictUri {
+    /** `"*"` selects every currently-registered conflict (bulk write only). */
+    id: number | "*";
+    scope?: ConflictScope;
+    /**
+     * When `raw` was a malformed `<file-prefix>:conflict://…` path, the
+     * stripped prefix is preserved here so callers can surface a gentle
+     * "you don't need the file path" note. `undefined` for clean URIs.
+     */
+    recoveredPrefix?: string;
+}
+/**
+ * Parse a `conflict://<N>`, `conflict://<N>/<scope>`, or `conflict://*` URI.
+ *
+ * Returns `null` for non-conflict paths; throws `ToolError` for a
+ * well-formed scheme with an invalid id or scope so the agent gets a
+ * clear actionable message rather than a confusing "not found" later.
+ *
+ * `*` is the bulk-write wildcard — only valid as `conflict://*` (no
+ * scope segment). Use it with `write({ path: "conflict://*", content })`
+ * to apply `content` (with optional `@ours` / `@theirs` / `@base` /
+ * `@both` shorthand) to every currently-registered conflict in one shot.
+ */
+export declare function parseConflictUri(raw: string): ParsedConflictUri | null;
+/** Result of {@link spliceConflict}: the new file text plus any boundary-echo repair applied. */
+export interface ConflictSplice {
+    text: string;
+    /** Replacement lines dropped because they duplicated the context directly above the region. */
+    trimmedLeading: number;
+    /** Replacement lines dropped because they duplicated the context directly below the region. */
+    trimmedTrailing: number;
+}
+/**
+ * Splice the conflict region recorded in `entry` out of `originalText`
+ * and replace it with `replacement` (markers and all sides included).
+ *
+ * Works like the edit tool's patch infra: locates the recorded marker
+ * block by content (anchored to `entry.startLine` as the preferred
+ * match), so out-of-band edits earlier in the file that shift line
+ * numbers don't break resolution. Throws clearly when the marker block
+ * has actually been altered or removed.
+ *
+ * Boundary-echo repair (same philosophy as the edit tool's hashline
+ * keeper repair): models frequently paste the "whole resolved function"
+ * including the lines that live directly before/after the marker block,
+ * which the verbatim splice would duplicate. Replacement lines that
+ * exactly echo the adjacent context are dropped when the echo is
+ * unambiguous — two or more consecutive lines, or a single line whose
+ * removal fixes a delimiter-balance mismatch against the recorded sides.
+ */
+export declare function spliceConflict(originalText: string, entry: ConflictEntry, replacement: string): ConflictSplice;
+/**
+ * True when two registered blocks record the same marker-block content
+ * (labels and all sides). Out-of-band edits can shift a block's line
+ * numbers between reads, registering a fresh id while the stale one
+ * persists; callers use content identity to treat a locate-miss for the
+ * stale twin as "already resolved" instead of a hard failure.
+ */
+export declare function conflictRegionsEqual(a: ConflictBlock, b: ConflictBlock): boolean;
+/**
+ * True when the entry's recorded marker block still occurs in `content`
+ * (LF-normalized — recorded sections are stored LF). Distinguishes a stale
+ * re-registration of a just-resolved region (no longer present) from a
+ * DISTINCT conflict block that happens to be byte-identical (still present
+ * elsewhere in the file and must stay addressable).
+ */
+export declare function conflictRegionPresent(content: string, entry: ConflictBlock): boolean;
+/**
+ * Expand `@ours` / `@theirs` / `@base` / `@both` line tokens against the
+ * recorded sections of `entry`. A token only triggers when it is the
+ * entire content of a line (after CRLF normalisation), so `@ours` inside
+ * actual code is left alone. Other lines pass through verbatim.
+ *
+ * - `@ours`    → expands to the recorded `oursLines` (in order).
+ * - `@theirs`  → expands to the recorded `theirsLines` (in order).
+ * - `@base`    → expands to `baseLines`; throws if no base section was
+ *               recorded (i.e. the conflict was 2-way, not diff3).
+ * - `@both`    → expands to `oursLines` then `theirsLines`.
+ */
+export declare function expandContentTokens(content: string, entry: ConflictEntry): string;
+/**
+ * Materialise a conflict block for `conflict://<N>` reads (and their
+ * `/ours` / `/theirs` / `/base` scopes).
+ *
+ * Returns:
+ * - `lines`: the lines to render, ordered top-to-bottom.
+ * - `startLine`: the 1-indexed file line number `lines[0]` corresponds
+ *   to, so the read formatter can label hashline anchors with the
+ *   original file positions.
+ *
+ * Bare (no scope) returns the full block including marker lines. A
+ * scoped view returns only that side's body — `base` throws when the
+ * recorded conflict is a 2-way merge with no base section.
+ */
+export declare function renderConflictRegion(entry: ConflictEntry, scope: ConflictScope | undefined): {
+    lines: string[];
+    startLine: number;
+};
+/**
+ * Build a compact diff-style footer describing the conflicts registered
+ * during a read. Designed to be appended after the file content.
+ *
+ * Format:
+ *
+ *     ⚠ N unresolved conflicts detected
+ *     - ours = HEAD
+ *     - theirs = feature/x
+ *     NOTICE: …
+ *
+ *     ──── #1  L42-48 ────
+ *     <<< ours
+ *     …ours body…
+ *     === base ≡ ours
+ *     >>> theirs
+ *     …theirs body…
+ *
+ * Labels are aggregated once at the top from the first entry that has
+ * them; when a section body equals another section's body the redundant
+ * body is collapsed to `≡ <other>`.
+ */
+export interface FormatConflictWarningOptions {
+    /**
+     * Total number of conflicts in the underlying file. If greater than
+     * `entries.length` the header notes how many are visible vs the total
+     * and points at `:conflicts` for the compact list.
+     */
+    totalInFile?: number;
+    /** Display path used inside the `:conflicts` hint. */
+    displayPath?: string;
+    /** Whether the underlying file scan hit its byte cap. */
+    scanTruncated?: boolean;
+}
+export declare function formatConflictWarning(entries: readonly ConflictEntry[], options?: FormatConflictWarningOptions): string;
+/**
+ * Render a single-line-per-block index of every conflict in a file.
+ * Used by the `<path>:conflicts` read selector to give the agent a cheap overview
+ * of a heavily-conflicted file without dumping every body.
+ */
+export declare function formatConflictSummary(entries: readonly ConflictEntry[], options?: {
+    displayPath: string;
+    scanTruncated?: boolean;
+}): string;

package/lib/types/tools/omp/tools/fetch.d.ts

@@ -0,0 +1,103 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { FetchImpl } from "@oh-my-pi/pi-ai";
+import type { Settings } from "../config/settings";
+import type { ToolSession } from "../sdk";
+import type { AgentStorage } from "../session/agent-storage";
+import { type OutputMeta } from "./output-meta";
+import { type LineRange } from "./path-utils";
+export interface ParsedReadUrlTarget {
+    path: string;
+    raw: boolean;
+    offset?: number;
+    limit?: number;
+    /** Populated only when the selector carries 2+ ranges. Single-range stays on offset/limit. */
+    ranges?: readonly LineRange[];
+}
+export declare function parseReadUrlTarget(readPath: string): ParsedReadUrlTarget | null;
+/** Reader backends for {@link renderHtmlToText}, in default priority order. */
+export type FetchProvider = "native" | "trafilatura" | "lynx" | "parallel" | "jina" | "browser";
+export declare const FETCH_PROVIDER_ORDER: readonly FetchProvider[];
+/**
+ * Render HTML to markdown by trying reader backends in priority order: native
+ * (in-process), trafilatura, lynx, Parallel, Jina, then the browser
+ * (headless-Chromium JS rendering, see {@link renderUrlWithBrowser} — gated
+ * behind `browser.readerEnabled`). The `providers.fetch` setting picks the
+ * order — `auto` uses the default above; any specific backend is tried first,
+ * then the remaining backends as fallbacks. Every backend's output must clear
+ * the same quality gate (>100 non-whitespace chars and not
+ * {@link isLowQualityOutput}) before it is accepted, otherwise the next
+ * backend is tried.
+ *
+ * When the raw HTML is a CSR app shell (script-heavy, text-light), output
+ * from {@link CSR_SUSCEPTIBLE} backends (which cannot execute page
+ * JavaScript) is held back as low quality so the chain still reaches the
+ * browser backend; with no usable browser the parked shell is returned as
+ * before, so degradation is unchanged. The browser's own output on a shell
+ * is accepted as-is (a noscript remnant is expected in it).
+ *
+ * The overall `timeout` budget bounds the whole call; remote backends (Parallel,
+ * Jina) are additionally capped at `REMOTE_READER_MAX_MS` so a hung endpoint
+ * cannot starve later renderers — especially the purely-local native converter,
+ * which always works on already-loaded HTML. Only a real `userSignal`
+ * cancellation aborts the chain (#1449).
+ */
+export declare function renderHtmlToText(url: string, html: string, timeout: number, settings: Settings, userSignal: AbortSignal | undefined, storage: AgentStorage | null, fetchOverride?: FetchImpl): Promise<{
+    content: string;
+    ok: boolean;
+    method: string;
+}>;
+/**
+ * Detect a client-side-rendered (CSR) app shell in raw HTML: script-dense
+ * markup with almost no statically visible text. Such pages only produce body
+ * content after JavaScript executes, so JS-unaware extractors (native/
+ * trafilatura/lynx) necessarily return a shell remnant (title/meta remnants)
+ * while the browser backend can render the real body. Deliberately
+ * conservative — compact HTML, multiple script tags, sparse static text — so
+ * genuine SSR pages are never flagged and their rendering order is unchanged.
+ * @returns true when the HTML looks like an unrendered SPA shell.
+ */
+export declare function isCsrHtmlShell(html: string): boolean;
+interface FetchImagePayload {
+    data: string;
+    mimeType: string;
+}
+export interface ReadUrlToolDetails {
+    kind: "url";
+    url: string;
+    finalUrl: string;
+    contentType: string;
+    method: string;
+    truncated: boolean;
+    notes: string[];
+    meta?: OutputMeta;
+    /** DSH (拍板#22): committed attachment facts when the URL image went through the bridge. */
+    image?: import("../../shared/image-bridge.ts").SavedImageRef;
+}
+interface ReadUrlEntry {
+    artifactId?: string;
+    artifactPath?: string;
+    details: ReadUrlToolDetails;
+    image?: FetchImagePayload;
+    output: string;
+    content: string;
+}
+/** Fetch and render a URL for a read or search operation. */
+export declare function fetchReadUrl(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal, options?: {
+    ensureArtifact?: boolean;
+}): Promise<ReadUrlEntry>;
+/** Materialize rendered URL body text to a local file for tools that require filesystem paths. */
+export declare function materializeReadUrlToFile(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal): Promise<{
+    path: string;
+    details: ReadUrlToolDetails;
+}>;
+export declare function executeReadUrl(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal): Promise<AgentToolResult<ReadUrlToolDetails>>;
+export {};

package/lib/types/tools/omp/tools/file-recorder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Creates a deduplicating recorder for relative file paths.
+ * Preserves insertion order in `list`; subsequent duplicates are ignored.
+ */
+export declare function createFileRecorder(): {
+    record: (relativePath: string) => void;
+    list: string[];
+};
+/**
+ * Strip native virtual-root prefixes and format file paths relative to cwd when
+ * they are inside cwd. Paths outside cwd remain absolute.
+ */
+export declare function formatResultPath(filePath: string, isDirectory: boolean, basePath: string, cwd: string): string;

package/lib/types/tools/omp/tools/fs-cache-invalidation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Invalidate shared filesystem scan caches after a content write/update.
+ */
+export declare function invalidateFsScanAfterWrite(path: string): void;
+/**
+ * Invalidate shared filesystem scan caches after deleting a file.
+ */
+export declare function invalidateFsScanAfterDelete(path: string): void;
+/**
+ * Invalidate shared filesystem scan caches after a rename/move.
+ *
+ * Some watchers care about the disappearance at the old path; others about the
+ * appearance at the new one. Bust both to keep callers honest.
+ */
+export declare function invalidateFsScanAfterRename(oldPath: string, newPath: string): void;