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

package/lib/types/tools/omp/tools/report-tool-issue.d.ts

@@ -0,0 +1,149 @@
+/**
+ * report_issue — automated QA backend for tracking unexpected tool behavior.
+ *
+ * No model-facing tool schema anymore: the write tool dispatches plain text to
+ * `xd://report_issue`, and the system prompt tells the model to write
+ * `<tool>: <concise description>` there when auto-QA is enabled.
+ *
+ * Enabled by default (`dev.autoqa` defaults to true); `PI_AUTO_QA=0` or an
+ * explicit `dev.autoqa: false` short-circuits injection entirely. When the
+ * user is only enabled by default (never configured `dev.autoqa` themselves),
+ * a persisted `dev.autoqaConsent: "denied"` also disables injection so a "No"
+ * in the consent dialog fully turns the feature off.
+ * Records grievances to a local SQLite database; never throws from the device
+ * dispatch path.
+ *
+ * Nothing is written until consent resolves. If the user has never been asked
+ * (`dev.autoqaConsent === "unset"`) the process-global consent handler —
+ * wired by `InteractiveMode` to a Yes/No popup — is invoked exactly once and
+ * the decision is persisted; a denial (or dismissal) drops the pending report
+ * without touching the database. Subsequent calls (including from subagents)
+ * read the cached decision without prompting. `PI_AUTO_QA_PUSH=1` bypasses
+ * the dialog for headless environments.
+ *
+ * When the user grants consent, push is automatically active against the
+ * bundled endpoint (`dev.autoqaPush.endpoint`, default `qa.omp.sh`). Each
+ * insert schedules a background flush that POSTs pending rows and deletes them
+ * on HTTP 2xx. `PI_AUTO_QA_PUSH=1` forces push in non-interactive environments
+ * where the consent dialog never fires. Device execution is never blocked on
+ * the network and never throws.
+ */
+import { Database } from "bun:sqlite";
+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 "./index";
+import type { XdevDispatch } from "./resolve";
+export declare const REPORT_ISSUE_DEVICE_NAME = "report_issue";
+export declare const REPORT_ISSUE_DEVICE_PATH = "xd://report_issue";
+/** Usage text for `read xd://report_issue`. */
+export declare function reportIssueDeviceUsage(): string;
+/** Whether a tool call writes to `xd://report_issue`. */
+export declare function isReportIssueToolCall(toolCall: {
+    name: string;
+    arguments?: Record<string, unknown>;
+}): boolean;
+/**
+ * Whether Auto-QA is active for this session.
+ *
+ * Precedence: `PI_AUTO_QA` env flag > explicit `dev.autoqa` setting >
+ * default-on unless the user previously denied consent. The denial veto only
+ * applies to the default: explicitly configuring `dev.autoqa: true` re-enables
+ * injection (recording still no-ops until consent is granted).
+ */
+export declare function isAutoQaEnabled(settings?: Settings): boolean;
+/**
+ * Resolver for the user's "share grievances?" consent.
+ *
+ * Return values:
+ *   - `true`  — user agreed; record + ship for this run and persist.
+ *   - `false` — user declined; suppress for this run and persist.
+ *   - `null`  — user dismissed the dialog (ESC, click-away, …) without
+ *               picking an option. The decision is NOT cached or persisted,
+ *               so the next `report_issue` invocation re-prompts.
+ *
+ * Persistence is the tool's job (so subagent invocations can persist into the
+ * disk-backed `Settings` instance the host registered alongside the handler),
+ * not the handler's. Implementations live in hosts that have UI affordances —
+ * today only `InteractiveMode`. When no handler is registered (CLI subcommands,
+ * tests, non-interactive runs) consent defaults to `false` — the explicit
+ * "don't collect by default" stance.
+ */
+export type AutoQaConsentHandler = () => Promise<boolean | null>;
+/**
+ * Register the consent handler and the persistent {@link Settings} instance
+ * the decision should be written to. Passing `null` clears the handler
+ * (e.g. on `InteractiveMode` teardown). Re-registration is authoritative.
+ */
+export declare function setAutoQaConsentHandler(handler: AutoQaConsentHandler | null, persistentSettings?: Settings | null): void;
+/** Test-only: clear consent cache + handler. Never call from production code. */
+export declare function __resetAutoQaConsentForTests(): void;
+/**
+ * Resolve the user's consent for Auto-QA grievances.
+ *
+ * Priority:
+ * 1. module cache (`cachedConsent`) — process-global, survives subagent boundaries
+ * 2. persisted setting on the caller's `Settings`
+ * 3. persisted setting on the registered persistent settings instance
+ * 4. registered UI handler (single-flight)
+ * 5. default `false` (no handler / non-interactive)
+ */
+export declare function resolveAutoQaConsent(settings: Settings | undefined): Promise<boolean>;
+/**
+ * Open (or return the cached handle for) the auto-QA SQLite database at
+ * `~/.omp/autoqa.db` (XDG: `$XDG_DATA_HOME/omp/autoqa.db`), creating the
+ * schema lazily. Returns `null` when the path cannot be resolved or opened.
+ */
+export declare function openAutoQaDb(): Database | null;
+export interface FlushResult {
+    pushed: number;
+    ok: boolean;
+    skipped?: boolean;
+}
+/**
+ * Optional per-flush controls. Used by `omp grievances push` to surface
+ * progress to a TTY and to skip the user-facing consent gate (manual
+ * pushes are the user's explicit intent, not a side effect of a device write).
+ */
+export interface FlushOptions {
+    /**
+     * Skip the `dev.autoqaConsent === "granted"` gate in
+     * {@link resolvePushConfig}. Endpoint configuration is still required.
+     * Reserved for explicit user-driven pushes (CLI `grievances push`,
+     * future debug recipes); never set from the device's auto-flush path.
+     */
+    bypassConsent?: boolean;
+    /**
+     * Fetch implementation for the push POST. Defaults to global fetch.
+     */
+    fetch?: FetchImpl;
+    /**
+     * Fires once at the start of the loop with the snapshot count of
+     * unpushed rows. Subsequent inserts won't be reflected (the count is
+     * a planning hint for progress reporters, not a live total).
+     */
+    onStart?: (totalUnpushed: number) => void;
+    /**
+     * Fires after every successfully shipped batch with the running pushed
+     * count. Reporters compare against the `totalUnpushed` they saw in
+     * `onStart` to advance their bar.
+     */
+    onProgress?: (pushedSoFar: number) => void;
+}
+/** Test-only: clear single-flight + cooldown state. Never call from production code. */
+export declare function __resetAutoQaFlushStateForTests(): void;
+/**
+ * Flush queued grievances to the configured backend.
+ */
+export declare function flushGrievances(db?: Database, settings?: Settings, options?: FlushOptions): Promise<FlushResult>;
+/** Test-only: await the last consent → insert → flush pipeline. */
+export declare function __awaitAutoQaRecordPipelineForTests(): Promise<void>;
+/**
+ * Execute `write xd://report_issue`. `text` must be either:
+ * - `<tool>: <concise description>` on one line, or
+ * - tool name on the first line with the report body below.
+ */
+export declare function dispatchReportIssueDevice(session: ToolSession, text: string): Promise<{
+    result: AgentToolResult<unknown>;
+    xdev: XdevDispatch;
+}>;

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

@@ -0,0 +1,127 @@
+/**
+ * Resolution devices: staged work is finalized through plain-text writes to
+ * always-available `xd://` URLs — no tool schema, no JSON protocol.
+ *
+ *   write xd://resolve   reason text  → APPLY the pending staged preview
+ *   write xd://reject    reason text  → DISCARD the pending staged preview
+ *   write xd://propose   plan <slug>  → submit the plan for approval (plan mode)
+ *
+ * Nothing rides the system prompt: the flows that stage work teach the call
+ * shape at the moment it becomes relevant (the preview reminder for
+ * resolve/reject, the plan-mode prompt for propose).
+ *
+ * Rendering rides the write tool's xd:// delegation: renderers.ts keys the
+ * resolve renderer under `resolve` and `reject` so device writes and legacy
+ * `resolve` tool transcripts draw the same block.
+ */
+import type { AgentToolResult, CustomMessage } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from ".";
+import type { ToolTier } from "./approval";
+/**
+ * Dispatch metadata carried on write-tool details for renderer delegation.
+ * （原 xdev.ts 的类型面；挂载设备层已随拍板剔除，仅 resolution/report_issue
+ * 设备继续在 write details 上携带此元数据。）
+ */
+export interface XdevDispatch {
+    tool: string;
+    mode: "help" | "execute";
+    /** Validated inner args, kept for renderer delegation on result rebuilds. */
+    args?: Record<string, unknown>;
+    /** Approval tier of the wrapped device call (`read` = no workspace mutation). */
+    tier?: ToolTier;
+    /** Details object returned by the wrapped tool, when executed. */
+    inner?: unknown;
+}
+export declare const RESOLVE_DEVICE_NAME = "resolve";
+export declare const REJECT_DEVICE_NAME = "reject";
+export declare const PROPOSE_DEVICE_NAME = "propose";
+/** The plain-text resolution device URLs (`xd://resolve`, …). */
+export declare const RESOLVE_DEVICE_PATH = "xd://resolve";
+export declare const REJECT_DEVICE_PATH = "xd://reject";
+export declare const PROPOSE_DEVICE_PATH = "xd://propose";
+/**
+ * Model-visible banner prepended to a staged preview's tool result text. The
+ * TUI badge (`⟨proposed⟩`) never reaches the model, and preview diffs are
+ * byte-identical to applied-edit output — without this line the model reads
+ * the result as an already-applied change.
+ */
+export declare const PREVIEW_PENDING_NOTICE = "Staged as a proposal \u2014 files NOT modified yet. To apply: write a one-sentence reason to xd://resolve. To discard: write to xd://reject.";
+export type ResolutionDeviceName = typeof RESOLVE_DEVICE_NAME | typeof REJECT_DEVICE_NAME | typeof PROPOSE_DEVICE_NAME;
+/** Whether an xd:// device name is one of the plain-text resolution devices. */
+export declare function isResolutionDeviceName(name: string): name is ResolutionDeviceName;
+/** One-line usage string returned by `read xd://<device>` — the only "docs" these devices carry. */
+export declare function resolutionDeviceUsage(device: ResolutionDeviceName): string;
+/**
+ * Whether an assistant tool call is a `write` targeting `xd://resolve` or
+ * `xd://reject`. Used as the SoftToolRequirement compliance check while a
+ * preview is pending — a plain `write` elsewhere resolves nothing.
+ */
+export declare function isPreviewResolutionToolCall(toolCall: {
+    name: string;
+    arguments?: Record<string, unknown>;
+}): boolean;
+/** Whether an assistant tool call is a `write` targeting `xd://propose` (plan-mode decision detection). */
+export declare function isProposeToolCall(toolCall: {
+    name: string;
+    arguments?: Record<string, unknown>;
+}): boolean;
+/**
+ * The XdevDispatch metadata carried on a completed `write` execution result, or
+ * `undefined` when the execution was not a device dispatch. Consumers check
+ * `.tool` (e.g. `PROPOSE_DEVICE_NAME` for plan-mode decision tracking and the
+ * event-controller's plan-approval hook).
+ */
+export declare function writeDeviceDispatch(toolName: string, result: unknown): XdevDispatch | undefined;
+/** Handler installed by plan mode; `xd://propose` dispatches the written plan title to it. */
+export type PlanProposalHandler = (title: string) => Promise<AgentToolResult<unknown>>;
+type ResolveAction = "apply" | "discard";
+/** Details payload carried on a resolve/reject dispatch result (`XdevDispatch.inner`). */
+export interface ResolveDetails {
+    action: ResolveAction;
+    reason: string;
+    sourceToolName?: string;
+    label?: string;
+    sourceResultDetails?: unknown;
+}
+/** Parse a completed `write` dispatch targeting `xd://resolve` or `xd://reject`. */
+export declare function resolveDispatchDetails(toolName: string, result: unknown): ResolveDetails | undefined;
+/**
+ * Register a non-forcing resolve-protocol handler for a staged preview. Wraps the
+ * caller's apply/reject into an onInvoked closure and stores it on the tool-choice
+ * queue's pending-invoker registry under a UNIQUE id. A `write` to `xd://resolve`
+ * or `xd://reject` dispatches to it; the agent-loop's SoftToolRequirement
+ * lifecycle injects the preview reminder and escalates to a forced `write` only
+ * if the model declines — so a compliant turn pays ZERO tool_choice change (no
+ * prompt-cache messages-cache invalidation).
+ *
+ * This is the canonical entry point for any tool that wants preview/apply
+ * semantics. No session-level abstraction is needed: callers pass their
+ * apply/reject functions directly. Resolution requires the `write` tool to be
+ * active — the session's soft requirement names it.
+ */
+export declare function queueResolveHandler(session: ToolSession, options: {
+    label: string;
+    sourceToolName: string;
+    apply(reason: string): Promise<AgentToolResult<unknown>>;
+    reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>;
+}): void;
+/**
+ * The canonical preview reminder. The resolve mechanism owns the wording; the
+ * agent-loop delivers it via the session's `SoftToolRequirement.reminder` (injected
+ * once per pending-preview head) instead of a host-side steer, so it lands as a
+ * stable mid-history append and never churns the cached prefix.
+ */
+export declare function buildResolveReminderMessage(sourceToolName: string): CustomMessage;
+/**
+ * Execute a resolution-device write. `text` is the raw plain-text body:
+ * - `xd://resolve` / `xd://reject` → the reason; dispatches to the pending
+ *   preview invoker (in-flight queue directive first).
+ * - `xd://propose` → the plan title; dispatches to the plan-proposal handler
+ *   installed by plan mode.
+ */
+export declare function dispatchResolutionDevice(session: ToolSession, device: ResolutionDeviceName, text: string): Promise<{
+    result: AgentToolResult<unknown>;
+    xdev: XdevDispatch;
+}>;
+export {};
+/** Streaming-safe call preview for a resolution-device write: `Resolve/Reject/Propose: <text>`. */

package/lib/types/tools/omp/tools/sqlite-reader.d.ts

@@ -0,0 +1,114 @@
+import type { Database } from "bun:sqlite";
+export declare function looksLikeSqlite(bytes: Uint8Array): boolean;
+/** Row cap for raw `?q=` SQL — protects against `SELECT *` on multi-million-row tables. */
+export declare const MAX_RAW_QUERY_ROWS = 1000;
+export interface SqlitePathCandidate {
+    sqlitePath: string;
+    subPath: string;
+    queryString: string;
+}
+export type SqliteSelector = {
+    kind: "list";
+} | {
+    kind: "schema";
+    table: string;
+    sampleLimit: number;
+} | {
+    kind: "row";
+    table: string;
+    key: string;
+} | {
+    kind: "query";
+    table: string;
+    limit: number;
+    offset: number;
+    order?: string;
+    where?: string;
+} | {
+    kind: "raw";
+    sql: string;
+};
+export type SqliteRowLookup = {
+    kind: "pk";
+    column: string;
+    type: string;
+} | {
+    kind: "rowid";
+};
+/**
+ * Row count for a table in the listing.
+ * - `exact`: counted in full (the table is small enough to count cheaply).
+ * - `estimate`: the planner's `sqlite_stat1` figure; the table is too large to
+ *   scan, so this may be stale.
+ * - `atLeast`: a lower bound; counting was capped before reaching the end.
+ */
+export type TableRowCount = {
+    kind: "exact";
+    rows: number;
+} | {
+    kind: "estimate";
+    rows: number;
+} | {
+    kind: "atLeast";
+    rows: number;
+};
+export interface SqliteTableSummary {
+    name: string;
+    count: TableRowCount;
+}
+export declare function parseSqlitePathCandidates(filePath: string): SqlitePathCandidate[];
+export declare function isSqliteFile(absolutePath: string): Promise<boolean>;
+export declare function parseSqliteSelector(subPath: string, queryString: string): SqliteSelector;
+export declare function listTables(db: Database, options?: {
+    probeCap?: number;
+}): SqliteTableSummary[];
+export declare function getTableSchema(db: Database, table: string): string;
+export declare function getTablePrimaryKey(db: Database, table: string): {
+    column: string;
+    type: string;
+} | null;
+export declare function resolveTableRowLookup(db: Database, table: string): SqliteRowLookup;
+export declare function queryRows(db: Database, table: string, opts: {
+    limit: number;
+    offset: number;
+    order?: string;
+    where?: string;
+}): {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    totalCount: number;
+};
+export declare function getRowByKey(db: Database, table: string, pk: {
+    column: string;
+    type?: string;
+}, key: string): Record<string, unknown> | null;
+export declare function getRowByRowId(db: Database, table: string, key: string): Record<string, unknown> | null;
+export declare function executeReadQuery(db: Database, sql: string): {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    truncated: boolean;
+};
+export declare function insertRow(db: Database, table: string, data: Record<string, unknown>): void;
+export declare function updateRowByKey(db: Database, table: string, pk: {
+    column: string;
+    type?: string;
+}, key: string, data: Record<string, unknown>): number;
+export declare function updateRowByRowId(db: Database, table: string, key: string, data: Record<string, unknown>): number;
+export declare function deleteRowByKey(db: Database, table: string, pk: {
+    column: string;
+    type?: string;
+}, key: string): number;
+export declare function deleteRowByRowId(db: Database, table: string, key: string): number;
+export declare function renderTableList(tables: SqliteTableSummary[]): string;
+export declare function renderSchema(createSql: string, sampleRows: {
+    columns: string[];
+    rows: Record<string, unknown>[];
+}): string;
+export declare function renderRow(row: Record<string, unknown>): string;
+export declare function renderTable(columns: string[], rows: Record<string, unknown>[], meta: {
+    totalCount: number;
+    offset: number;
+    limit: number;
+    table: string;
+    dbPath: string;
+}): string;

package/lib/types/tools/omp/tools/tool-errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Standardized error types for tool execution.
+ *
+ * Tools should throw these instead of returning error text.
+ * The agent loop catches and renders them appropriately.
+ */
+/**
+ * Base error for tool execution failures.
+ * Override render() for custom LLM-facing formatting.
+ */
+export declare class ToolError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+    /** Render error for LLM consumption. Override for custom formatting. */
+    render(): string;
+}
+/**
+ * Error thrown when a tool operation is aborted (e.g., via AbortSignal).
+ */
+export declare class ToolAbortError extends Error {
+    static readonly MESSAGE = "Operation aborted";
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Throw ToolAbortError if the signal is aborted.
+ * Use this instead of signal?.throwIfAborted() to get consistent error types.
+ */
+export declare function throwIfAborted(signal?: AbortSignal): void;
+/**
+ * Render an error for LLM consumption.
+ * Handles ToolError.render() and falls back to message/string.
+ */
+export declare function renderError(e: unknown): string;

package/lib/types/tools/omp/tools/tool-result.d.ts

@@ -0,0 +1,33 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
+import type { OutputSummary, TruncationResult } from "../session/streaming-output";
+import type { OutputMeta, TruncationOptions, TruncationSummaryOptions, TruncationTextOptions } from "./output-meta";
+type ToolContent = Array<TextContent | ImageContent>;
+type DetailsWithMeta = {
+    meta?: OutputMeta;
+};
+export declare class ToolResultBuilder<TDetails extends DetailsWithMeta> {
+    #private;
+    constructor(details?: TDetails);
+    text(text: string): this;
+    content(content: ToolContent): this;
+    truncation(result: TruncationResult, options: TruncationOptions): this;
+    truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this;
+    truncationFromText(text: string, options: TruncationTextOptions): this;
+    limits(limits: {
+        matchLimit?: number;
+        resultLimit?: number;
+        headLimit?: number;
+        columnMax?: number;
+    }): this;
+    sourceUrl(value: string): this;
+    sourcePath(value: string): this;
+    sourceInternal(value: string): this;
+    /** Flag the result as a non-throwing failure (agent-loop surfaces it as a tool error). */
+    error(value?: boolean): this;
+    /** Marks the result contextually useless — compaction may elide it once consumed. */
+    useless(value?: boolean): this;
+    done(): AgentToolResult<TDetails>;
+}
+export declare function toolResult<TDetails extends DetailsWithMeta>(details?: TDetails): ToolResultBuilder<TDetails>;
+export {};

package/lib/types/tools/omp/tools/tool-timeouts.d.ts

@@ -0,0 +1,57 @@
+export interface ToolTimeoutConfig {
+    /** Default timeout in seconds when agent omits the field */
+    default: number;
+    /** Minimum allowed timeout in seconds */
+    min: number;
+    /** Maximum allowed timeout in seconds (per-tool ceiling) */
+    max: number;
+}
+export declare const TOOL_TIMEOUTS: {
+    readonly bash: {
+        readonly default: 300;
+        readonly min: 1;
+        readonly max: 3600;
+    };
+    readonly eval: {
+        readonly default: 30;
+        readonly min: 1;
+        readonly max: 3600;
+    };
+    readonly browser: {
+        readonly default: 30;
+        readonly min: 1;
+        readonly max: 300;
+    };
+    readonly computer: {
+        readonly default: 120;
+        readonly min: 1;
+        readonly max: 300;
+    };
+    readonly ssh: {
+        readonly default: 60;
+        readonly min: 1;
+        readonly max: 3600;
+    };
+    readonly fetch: {
+        readonly default: 20;
+        readonly min: 1;
+        readonly max: 45;
+    };
+    readonly debug: {
+        readonly default: 30;
+        readonly min: 5;
+        readonly max: 300;
+    };
+};
+export type ToolWithTimeout = keyof typeof TOOL_TIMEOUTS;
+/**
+ * Clamp a raw timeout to the allowed range for a tool.
+ *
+ * When `rawTimeout` is undefined the tool's `default` is used. A positive
+ * `maxTimeout` (the `tools.maxTimeout` global ceiling) caps the *resolved*
+ * value — including the default-fallback path — before the per-tool `min`/`max`
+ * floor and ceiling apply, so a configured global cap governs calls where the
+ * agent omits `timeout`, not only explicitly-passed values. `maxTimeout <= 0`
+ * means no global cap.
+ */
+export declare function clampTimeout(tool: ToolWithTimeout, rawTimeout?: number, maxTimeout?: number): number;

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

@@ -0,0 +1,53 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolApprovalDecision } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from "../../omp/sdk.ts";
+import type { OutputMeta } from "../../omp/tools/output-meta.ts";
+import { type XdevDispatch } from "../../omp/tools/resolve.ts";
+declare const writeSchema: import("@oh-my-pi/omptype").FluentType<{
+    path: string;
+    content: string;
+}, {
+    path: string;
+    content: string;
+}>;
+export type WriteToolInput = typeof writeSchema.infer;
+/** Details returned by the write tool for TUI rendering */
+export interface WriteToolDetails {
+    meta?: OutputMeta;
+    /** Set when the file was auto-chmod'd because content begins with a `#!` shebang. */
+    madeExecutable?: boolean;
+    /** Absolute filesystem path the write resolved to. Used by the renderer to wrap
+     * the (possibly cwd-relative) header path in an OSC 8 `file://` hyperlink. */
+    resolvedPath?: string;
+    /** Set when the write dispatched an `xd://` tool device; drives renderer delegation. */
+    xdev?: XdevDispatch;
+}
+type WriteParams = WriteToolInput;
+/**
+ * Write tool implementation.
+ *
+ * Creates or overwrites files with optional LSP formatting and diagnostics.
+ */
+export declare class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "write";
+    readonly approval: (args: unknown) => ToolApprovalDecision;
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    readonly label = "Write";
+    readonly description: string;
+    readonly parameters: import("@oh-my-pi/omptype").FluentType<{
+        path: string;
+        content: string;
+    }, {
+        path: string;
+        content: string;
+    }>;
+    readonly strict = true;
+    readonly concurrency = "exclusive";
+    readonly loadMode = "essential";
+    /** Stream matchers should see the real file content, not its JSON-escaped argument encoding. */
+    matcherDigest(args: unknown): string | undefined;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, { path: rawPath, content }: WriteParams, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<WriteToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<WriteToolDetails>>;
+}
+export {};

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

@@ -0,0 +1,24 @@
+/**
+ * File-write channel for the write/edit engines.
+ *
+ * OMP routes every edit/write through an LSP writethrough (format +
+ * diagnostics). DSH has no LSP infrastructure (plan.md 拍板#5 cuts LSP), so
+ * the channel performs the actual file write directly: the edit itself is
+ * fully functional; formatting/diagnostics simply do not exist as a DSH
+ * capability. LSP-only parameters (batch request, deferred-diagnostics
+ * handle) are not part of the DSH signature.
+ */
+/**
+ * Callback type for the file write channel. DSH's writethrough writes the
+ * content to `dst` (via the provided file handle when present) and returns
+ * nothing.
+ */
+export type WritethroughCallback = (dst: string, content: string, signal?: AbortSignal, file?: {
+    write(content: string): Promise<void>;
+}) => Promise<void>;
+/** Write `content` to `dst` (or the passed file handle) — no LSP pass. */
+export declare function writethroughNoop(dst: string, content: string, _signal?: AbortSignal, file?: {
+    write(content: string): Promise<void>;
+}): Promise<void>;
+/** Async UTF-8 write (node:fs) used when no file handle is supplied. */
+export declare function writeFileUtf8(dst: string, content: string): Promise<void>;

package/lib/types/tools/omp/utils/block-context.d.ts

@@ -0,0 +1,35 @@
+export interface LineSpan {
+    startLine: number;
+    endLine: number;
+}
+/** Where the source came from, so tree-sitter can pick a grammar. */
+export interface BlockContextSource {
+    path?: string;
+    lang?: string;
+}
+export type LineEntry = {
+    kind: "line";
+    lineNumber: number;
+    text: string;
+    context: boolean;
+} | {
+    kind: "ellipsis";
+};
+/**
+ * Resolve the off-window boundary lines for a visible window: tree-sitter
+ * syntactic spans first (covers brace and indentation languages), falling back
+ * to a lexical bracket scan when the grammar is unavailable. Returns a map of
+ * `lineNumber → source text` for the lines to surface, never including a line
+ * already visible.
+ */
+export declare function findBlockContextLines(fullLines: readonly string[], visibleInput: ReadonlySet<number> | readonly number[], source?: BlockContextSource): Map<number, string>;
+/**
+ * Build display entries for `visibleSpans` plus any off-window block-boundary
+ * lines, in source order, with `{ kind: "ellipsis" }` markers inserted across
+ * non-contiguous gaps. `options.lineText` lets callers substitute display text
+ * (e.g. column-truncated lines) for a given line number.
+ */
+export declare function buildLineEntriesWithBlockContext(fullLines: readonly string[], visibleSpans: readonly LineSpan[], source?: BlockContextSource, options?: {
+    lineText?: (lineNumber: number, sourceText: string, context: boolean) => string;
+}): LineEntry[];
+export declare function lineEntriesToPlainText(entries: readonly LineEntry[], ellipsis?: string): string;