import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
import type { ReadToolDetails } from "@oh-my-pi/pi-tui/tools/read";
import type { ToolSession } from "../sdk.js";
import { type SuffixMatchCache } from "./read-path-resolution.js";
/** One page of query results requested via `offset`/`limit`. */
export interface JsonPage {
    offset: number;
    limit: number;
}
/** Options parsed from the query string of a `file.json?q=<filter>` read. */
export interface JsonSelector {
    query: string;
    raw: boolean;
    compact: boolean;
    /** Present when `offset` or `limit` asks for a page instead of the whole output. */
    page?: JsonPage;
}
/**
 * Splits a selector target at its first `?`, independently of the file extension.
 * Admission still requires recognized parameters and an existing non-image file.
 */
export declare function splitJsonQueryTarget(readPath: string): {
    jsonPath: string;
    queryString: string;
} | null;
/**
 * Parses `q`/`query`, `raw`, `compact`, `offset`, and `limit`.
 * Modifiers or an empty filter imply `.`; unknown-only query strings return null.
 * `q` is percent-decoded but never form-decoded, so jq's `+` survives.
 */
export declare function parseJsonSelector(queryString: string): JsonSelector | null;
/**
 * Evaluates `selector.query` over `filePath` with the bundled jaq.
 *
 * Without a page, returns jaq's output verbatim (minus the final newline).
 * With one, jaq runs compact so each line is exactly one value and stops once
 * the page plus one lookahead value is captured; a single array result pages
 * its elements instead. Values are re-rendered from text, never reparsed.
 * Anything jaq wrote to stderr leads the result.
 *
 * @throws ToolError on jq errors and timeouts, or when the values before the
 * requested page exceed the capture cap.
 */
export declare function executeJsonQuery(filePath: string, selector: JsonSelector, signal?: AbortSignal): Promise<string>;
/** A JSON file path with its parsed selector, ready for {@link readJson}. */
export interface ResolvedJsonReadPath {
    absolutePath: string;
    selector: JsonSelector;
    suffixResolution?: {
        from: string;
        to: string;
    };
}
/** An already-bounded virtual text resource, queried locally without exposing scratch paths. */
export interface ResolvedJsonReadResource {
    url: string;
    content: string;
    selector: JsonSelector;
}
/**
 * Resolves `file?q=…` to an existing non-image file, falling back to a unique
 * workspace suffix match; null when the path is not a JSON query or no file exists.
 */
export declare function resolveJsonReadPath(session: ToolSession, readPath: string, suffixCache: SuffixMatchCache, signal?: AbortSignal): Promise<ResolvedJsonReadPath | null>;
/** Runs a resolved JSON query and renders it as a read result; `lineSelector` slices the output. */
export declare function readJson(session: ToolSession, resolvedJsonPath: ResolvedJsonReadPath | ResolvedJsonReadResource, lineSelector?: string, signal?: AbortSignal): Promise<AgentToolResult<ReadToolDetails>>;