/**
 * G2 (2026-08-13): 结构化错误分类体系 + trace_id 生成。
 *
 * 借鉴 xulek `_classify_exception` / `_new_trace_id`(附录 H 标杆),移植到 enhanced。
 *
 * PII 护栏(核心):分类从异常【类型】映射,绝不读 err.message。
 * 旧 safeErrorCategory 曾把含路径/项目名的错误文本塞进 error_category 外传 PII
 * (见 ToolDispatcher.ts 506-510 历史注释);本模块用结构化异常类型替代文本推断,
 * 让分类可精细化的同时不再有 PII 外传风险。
 *
 * 用法:throw new PathError() / new ConnectionError() 等;主 catch 用 classifyError(err)
 * 拿 {category, retryable, code, safeMessage},safeMessage 进 client 响应,
 * 完整 err.message 只 log() 到 server 日志。
 */
export type ErrorCategory = 'validation' | 'timeout' | 'transport' | 'guard' | 'path' | 'connection' | 'internal';
export interface ClassifiedError {
    category: ErrorCategory;
    retryable: boolean;
    code: string;
    /** PII-safe message — 不含路径/项目名,可进 client 响应。完整 err.message 只 log。 */
    safeMessage: string;
}
/**
 * 基类:所有结构化工具错误。
 * 子类设默认 category / retryable / code;构造时传 PII-safe 的 safeMessage。
 * 父类 Error.message 也用 safeMessage(避免误传 PII);如需保留详细文本供 log,
 * 调用方在 catch 里 `log(err instanceof Error ? err.message : String(err))` 单独打。
 */
export declare class ToolError extends Error {
    readonly code: string;
    readonly category: ErrorCategory;
    readonly retryable: boolean;
    readonly safeMessage: string;
    constructor(code: string, category: ErrorCategory, retryable: boolean, safeMessage: string);
}
/** 参数校验失败(不可重试)。 */
export declare class ValidationError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/** 路径校验失败:不在白名单 / 穿越 / 非法字符(不可重试,PII 高发区)。 */
export declare class PathError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/** 编辑器/bridge 未连接(可重试 — 重连后可成功)。 */
export declare class ConnectionError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/** 操作超时(可重试)。 */
export declare class TimeoutError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/** 传输层错误:socket 断开等非超时(可重试)。 */
export declare class TransportError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/** 守卫拒绝(确认令牌/只读模式拦截,不可重试)。 */
export declare class GuardError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/** 速率限制(瞬态,可重试 — 与 GuardError 拒绝区分)。归 guard category 但 retryable=true。 */
export declare class RateLimitError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/** 内部错误(不可重试,PII-safe 固定兜底)。 */
export declare class InternalError extends ToolError {
    constructor(safeMessage?: string, code?: string);
}
/**
 * Classify an unknown thrown value into a structured error.
 *
 * ToolError 子类走结构化字段;原生 Error / 其它值兜底成 internal(PII-safe 固定 message)。
 * **绝不读 err.message 作为 safeMessage**(防 PII 外传)。
 */
export declare function classifyError(err: unknown): ClassifiedError;
/** Generate a 16-hex trace id(对齐 xulek `_new_trace_id`,AI 易读)。单 server 不用 W3C traceparent。 */
export declare function newTraceId(): string;