import type { Host } from "../host/host.js";
/** The source of a saved output, by its name; null when unknown. */
export type SpillLookup = (name: string) => string | null;
export type TraceOptions = {
    columns: number;
    color: boolean;
    /** Append the registered tool name to summary lines (debug mode). */
    toolNames?: boolean;
    spillSource?: SpillLookup;
};
export type ToolStartEvent = {
    kind: "toolStart";
    toolName: string;
    args: unknown;
    provider?: string | null;
};
export type ToolEndEvent = {
    kind: "toolEnd";
    toolName: string;
    args?: unknown;
    value: unknown;
    outcome: "success" | "failure" | "plain";
    /** Milliseconds the call took. */
    timeTaken?: number;
    provider?: string | null;
};
export type HostedSearchEvent = {
    kind: "hostedSearch";
    result: unknown;
};
export type AgentStartEvent = {
    kind: "agentStart";
    toolName: string;
    message: string;
};
export type SessionSaveFailureEvent = {
    kind: "sessionSaveFailure";
    message: string;
};
export type AgentTraceEvent = ToolStartEvent | ToolEndEvent | HostedSearchEvent | AgentStartEvent | SessionSaveFailureEvent;
export type ToolArgs = Record<string, unknown>;
/** A value as one piece of a line: a string, a number, or a string array
 *  joined by spaces. Anything else, or an empty string, is skipped. */
export declare function text(value: unknown): string | null;
export declare function prefixed(prefix: string, value: unknown): string | null;
/** `dir/filename`, with `dir` dropped when it is missing or `.`. */
export declare function filePath(args: ToolArgs): string | null;
/** The lines a read covered, by the `sliceLines` rule: `offset` is the
 *  1-based first line and `limit` a count, each 0 when unset. */
export declare function lineRange(args: ToolArgs): string | null;
/** `baseUrl` with `path` appended when the call set one. */
export declare function urlWithPath(args: ToolArgs): string | null;
/** `word` when the boolean argument is true. */
export declare function flag(args: ToolArgs, key: string, word: string): string | null;
/** `output of <source>` for a saved output the store knows, else the name. */
export declare function spillOutput(name: unknown, lookup: SpillLookup): string | null;
/** What a command printed, for a human: stderr when there is any, else
 *  stdout. A spill notice is cut to its first line, which carries the size
 *  and exit code; the rest is written for the model. */
export declare function commandDetail(stdout: unknown, stderr: unknown): string | null;
/** The tools with a row, for the test that checks every agent tool has one. */
export declare function presentedToolNames(): string[];
export declare function traceOptionsForHost(host: Host, toolNames?: boolean): TraceOptions;
/** Describe an event first; only the renderer knows about terminal layout. */
export declare function formatAgentTrace(event: AgentTraceEvent, options: TraceOptions): string;
/** One write keeps concurrent tool blocks together. */
export declare function printAgentTrace(host: Host, event: AgentTraceEvent, toolNames?: boolean): void;
/** The Agency bridge. `toolNames` is the agent's debug flag. */
export declare function _printAgentTrace(event: AgentTraceEvent, toolNames?: boolean): void;