@xiaoso/dsh-tool-plus 0.1.6 → 0.1.7-beta.1

package/lib/types/tools/omp/tools/read-selector.d.ts

@@ -0,0 +1,27 @@
+import type { LineRange } from "../../omp/tools/path-utils.ts";
+/** Parsed representation of a path-embedded selector. */
+export type ParsedSelector = {
+    kind: "none";
+} | {
+    kind: "raw";
+} | {
+    kind: "conflicts";
+} | {
+    kind: "lines";
+    ranges: [LineRange, ...LineRange[]];
+    raw?: boolean;
+};
+/** Returns true when the selector requested verbatim/raw output (alone or combined with a range). */
+export declare function isRawSelector(parsed: ParsedSelector): boolean;
+/** Returns true when the selector requested multiple line ranges. */
+export declare function isMultiRange(parsed: ParsedSelector): boolean;
+export declare function parseSel(sel: string | undefined): ParsedSelector;
+/**
+ * Convert a single-range selector to the offset/limit pair used by internal pagination.
+ * Returns the FIRST range only — multi-range callers MUST branch on `isMultiRange` before
+ * calling this helper.
+ */
+export declare function selToOffsetLimit(parsed: ParsedSelector): {
+    offset?: number;
+    limit?: number;
+};

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

@@ -0,0 +1,16 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from "../../omp/sdk.ts";
+import type { ReadToolDetails } from "./read";
+import { type SuffixMatchCache } from "./read-path-resolution";
+interface ResolvedSqliteReadPath {
+    absolutePath: string;
+    sqliteSubPath: string;
+    queryString: string;
+    suffixResolution?: {
+        from: string;
+        to: string;
+    };
+}
+export declare function resolveSqliteReadPath(session: ToolSession, readPath: string, suffixCache: SuffixMatchCache, signal?: AbortSignal): Promise<ResolvedSqliteReadPath | null>;
+export declare function readSqlite(resolvedSqlitePath: ResolvedSqliteReadPath, signal?: AbortSignal): Promise<AgentToolResult<ReadToolDetails>>;
+export {};

package/lib/types/tools/omp/tools/read-summary.d.ts

@@ -0,0 +1,15 @@
+import { type SummaryResult } from "@oh-my-pi/pi-natives";
+import type { ToolSession } from "../../omp/sdk.ts";
+import { type ElidedRange } from "./read-format";
+/**
+ * Prose files (Markdown flavors and plain text) skip code-block summarization
+ * unless `read.summarize.prose` opts them in.
+ */
+export declare function isProseSummaryPath(filePath: string): boolean;
+export declare function trySummarize(session: ToolSession, absolutePath: string, fileSize: number, signal?: AbortSignal): Promise<SummaryResult | null>;
+export declare function renderSummary(session: ToolSession, summary: SummaryResult): {
+    text: string;
+    displayText: string;
+    elidedRanges: ElidedRange[];
+    elidedLines: number;
+};

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

@@ -0,0 +1,70 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolTier } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from "../../omp/sdk.ts";
+import { type TruncationResult } from "../../omp/session/streaming-output.ts";
+import { type OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const readSchema: import("@oh-my-pi/omptype").FluentType<{
+    path: string;
+}, {
+    path: string;
+}>;
+export type ReadToolInput = typeof readSchema.infer;
+export interface ReadToolDetails {
+    kind?: "file" | "url";
+    truncation?: TruncationResult;
+    isDirectory?: boolean;
+    resolvedPath?: string;
+    suffixResolution?: {
+        from: string;
+        to: string;
+    };
+    /** DSH image bridge (拍板#22): committed attachment facts for an image read. */
+    image?: import("../../shared/image-bridge.ts").SavedImageRef;
+    url?: string;
+    finalUrl?: string;
+    contentType?: string;
+    method?: string;
+    notes?: string[];
+    meta?: OutputMeta;
+    /** Full on-disk byte size recorded before applying a file range. */
+    fileSize?: number;
+    /** Full source line count when the read reached EOF and the count is exact. */
+    totalLines?: number;
+    /** Raw text + start line for user-visible TUI rendering, set when content is text-like.
+     * Mirrors the same lines the model receives but without hashline/line-number prefixes,
+     * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
+    displayContent?: {
+        text: string;
+        startLine: number;
+        lineNumbers?: Array<number | null>;
+    };
+    summary?: {
+        lines: number;
+        elidedSpans: number;
+        elidedLines: number;
+    };
+    /** Number of unresolved git conflicts surfaced by this read (TUI uses for inline `⚠ N` badge). */
+    conflictCount?: number;
+    /** Paths recovered from a delimited read argument; used only by the TUI to render one call as multiple read rows. */
+    displayReadTargets?: string[];
+}
+type ReadParams = ReadToolInput;
+/**
+ * Read tool implementation.
+ *
+ * Reads files with support for images, converted documents (via markit), and text.
+ * Directories return a formatted listing with modification times.
+ */
+export declare class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "read";
+    readonly approval: (args: unknown) => ToolTier;
+    readonly label = "Read";
+    readonly loadMode = "essential";
+    description: string;
+    get parameters(): typeof readSchema;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: ReadParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<ReadToolDetails>, _toolContext?: AgentToolContext): Promise<AgentToolResult<ReadToolDetails>>;
+}
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * Formatting helpers shared by the tool engines.
+ *
+ * The TUI renderer utilities that used to live here were cut with the TUI
+ * layer (plan.md 拍板#17); what remains is what the engines themselves use.
+ */
+export { replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
+export { formatAge, formatBytes, formatCount, formatDuration, pluralize } from "@oh-my-pi/pi-utils";
+/**
+ * Extract domain from URL, stripping www. prefix.
+ */
+export declare function getDomain(url: string): string;
+export declare function shortenPath(filePath: unknown, homeDir?: string): string;
+export type CodeFrameMarker = "" | " " | "*" | "+" | "-" | ">";
+export declare function formatCodeFrameLine(marker: CodeFrameMarker, lineNumber: string | number, content: string, lineNumberWidth: number): string;
+export declare const PARSE_ERRORS_LIMIT = 20;
+export declare function dedupeParseErrors(errors: string[] | undefined): string[];
+export declare function formatParseErrors(errors: string[], total?: number): string[];
+/**
+ * Cap an upstream parse-error list to {@link PARSE_ERRORS_LIMIT} unique entries,
+ * preserving the original deduplicated total. Use this at the source so tool
+ * details never carry thousands of per-file parse errors into traces or
+ * renderers.
+ */
+export declare function capParseErrors(errors: string[] | undefined, limit?: number): {
+    errors: string[];
+    total: number;
+};

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 {};