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 size/type summary (not yet implemented; falls back to `tail`)
     */
    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;
}
/**
 * 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;
}
/**
 * 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