import type { ToolResult } from '../../types/tools.js';
import { OverflowHandler } from '../../tools/shared/overflow.js';
import type { SpillBackendType } from '../../tools/shared/overflow.js';
/**
 * ToolClass, semantic classification of a tool's output characteristics.
 *
 * Mirrors `PhasedTool.category` but adds `analyze` for analytical/inspection
 * tools that produce structured summaries rather than raw data.
 */
export type ToolClass = 'read' | 'write' | 'execute' | 'network' | 'analyze';
/**
 * ToolOutputPolicy, limits and behaviour rules applied to every tool result
 * of a given class before it reaches the LLM context window.
 */
export interface ToolOutputPolicy {
    /**
     * Identifies which tool class this policy governs.
     * Used as the stable `policyId` in audit records.
     */
    toolClass: ToolClass;
    /**
     * Soft token ceiling (estimated as chars / 4).
     * Enforcement is informational, `maxBytes` is the hard limit.
     */
    maxTokens: number;
    /**
     * Hard byte ceiling for the serialised output string.
     * Output exceeding this limit is truncated or spilled.
     */
    maxBytes: number;
    /**
     * Where to cut when output exceeds `maxBytes`.
     *
     * - `tail`   , keep the beginning, drop the end (default for most classes)
     * - `head`   , keep the end, drop the beginning (useful for execute stdout)
     * - `middle` , keep both ends, drop the middle
     * - `summary`, replace with a compact size/type summary
     */
    truncationMode: 'tail' | 'head' | 'middle' | 'summary';
    /**
     * Where to put content that exceeds the byte limit.
     *
     * - `inline`   , truncate in-place, append an ellipsis note
     * - `file`     , spill to `.goodvibes/.overflow/`, embed a path reference
     * - `reference`, replace content with a compact reference marker only
     */
    spillMode: 'inline' | 'file' | 'reference';
    /**
     * Whether to attach an `OutputPolicyResult` audit record to the transformed
     * `ToolResult`.  Always `true` for production policies; can be set `false`
     * in lightweight / test contexts.
     */
    auditMetadata: boolean;
}
/**
 * OutputPolicyResult, audit record produced by `applyOutputPolicy`.
 * Attached to the transformed `ToolResult` as `_policyAudit`.
 */
export interface OutputPolicyResult {
    /** Stable identifier matching `ToolOutputPolicy.toolClass`. */
    policyId: string;
    /**
     * What the policy enforcement actually did:
     * - `none`      , output was within limits; no transformation applied
     * - `truncated` , output was cut to fit within `maxBytes`
     * - `spilled`   , overflow was written to disk; a reference was embedded
     * - `referenced`, output replaced by a compact reference marker
     */
    actionTaken: 'none' | 'truncated' | 'spilled' | 'referenced';
    /** Original output byte length before policy enforcement. */
    originalSize: number;
    /** Output byte length after policy enforcement. */
    resultSize: number;
    /**
     * Backend type used when `actionTaken === 'spilled'`.
     * Undefined for other action types.
     */
    spillBackend?: SpillBackendType | undefined;
}
/**
 * ToolResultWithAudit, a `ToolResult` with an optional policy audit record
 * injected by `applyOutputPolicy`.
 *
 * The base `ToolResult` interface is left unmodified; this extension is the
 * only carrier of audit data so the core type surface stays stable.
 */
export interface ToolResultWithAudit extends ToolResult {
    /** Policy audit record, present on every result that passed through output-policy. */
    _policyAudit?: OutputPolicyResult | undefined;
}
/**
 * DEFAULT_POLICIES, one policy per tool class.
 *
 * Byte limits are calibrated to stay well under typical LLM context windows:
 * - read    : 200 KB, file reads can be large; spill remainder to disk
 * - write   : 32 KB , confirmations should be concise; inline truncation
 * - execute : 128 KB, command output can be chatty; keep tail (most recent)
 * - network : 256 KB, remote responses can be large; spill to disk
 * - analyze : 64 KB , structured summaries; inline truncation
 */
export declare const DEFAULT_POLICIES: Readonly<Record<ToolClass, ToolOutputPolicy>>;
/**
 * Returns the output policy for the given tool class.
 * Always returns a defined policy, falls back to the `read` policy if
 * an unrecognised class is supplied (should never happen in strict TypeScript
 * but guards against runtime extension points).
 *
 * @param toolClass - The class of the tool whose policy to retrieve.
 */
export declare function getPolicy(toolClass: ToolClass): ToolOutputPolicy;
/**
 * Applies the output policy to a tool result, enforcing byte limits and
 * attaching an audit record.
 *
 * The input `result` is **mutated in place** (output field updated) and also
 * returned as `ToolResultWithAudit` so callers can use the return value
 * directly without re-reading `record.result`.
 *
 * @param result - The raw tool result to enforce limits on.
 * @param policy - The policy to apply (obtain via `getPolicy`).
 * @returns The mutated result with `_policyAudit` attached, plus a standalone
 *          `OutputPolicyResult` audit record.
 */
export declare function applyOutputPolicy(result: ToolResult, policy: ToolOutputPolicy, overflowHandler: OverflowHandler): {
    result: ToolResultWithAudit;
    audit: OutputPolicyResult;
};
//# sourceMappingURL=output-policy.d.ts.map