/**
 * Append helpers for durable, log-only hook events. They carry no surface
 * intent and must remain turn-enclosed and invoked/result paired. Mid-turn hook
 * points satisfy that boundary; SessionStart records injected context instead
 * and does not append `hook/*` outside a turn.
 * @module @deepseek-ai/dsh-hook-protocol/events
 */
import type { Session } from '@deepseek-ai/dsh-session';
import type { HookDialect, HookOutput } from './types.ts';
/** What identifies a hook invocation across its invoked/result pair. */
export interface HookInvocation {
    /** The open turn the invocation lives inside. */
    turn: number;
    /** The hook point (`PreToolUse`, `Stop`, …). */
    point: string;
    /** The bridge dialect that ran it. */
    dialect: HookDialect;
    /** A stable id correlating the invoked event with its result. */
    handlerId: string;
    /** The matcher-group pattern that selected it (absent for match-all). */
    matcher?: string;
}
/** The decided outcome half of the pair. */
export interface HookResultRecord {
    turn: number;
    point: string;
    handlerId: string;
    /**
     * The decoded outcome the run produced. {@link appendHookResult} derives the
     * durable `decision`/`exitCode`/`stderrSummary` fields from it, so the shared
     * event's semantics live here, in the lib that declares it, not per-bridge.
     */
    output: HookOutput;
    /**
     * Character cap for the derived `stderrSummary`. The bound is the bridge's
     * to own (its `stderrSummaryMaxChars` config) and is passed in explicitly —
     * {@link DEFAULT_STDERR_SUMMARY_MAX_CHARS} is the reference default.
     */
    stderrSummaryMaxChars: number;
    /** Wall-clock duration of the run (from `runHook`) — durable audit timing. */
    durationMs: number;
}
/**
 * The reference default for {@link HookResultRecord.stderrSummaryMaxChars}
 * (both bridges' config default). It lives here, once, next to the truncation
 * rule it bounds, so the bridges cannot drift apart on the shared event's
 * default cap.
 */
export declare const DEFAULT_STDERR_SUMMARY_MAX_CHARS = 500;
/**
 * Truncate a hook's stderr for {@link HookResultRecord.stderrSummary}: trimmed,
 * `undefined` when empty, cut at `maxChars` with an ellipsis when over. The
 * bound is a parameter — like `runHook`'s `defaultTimeoutMs`, each bridge owns
 * the config default and passes it in.
 * @param stderr - the hook's raw captured stderr.
 * @param maxChars - the character cap for the summary (the bridge's config value).
 * @returns the trimmed, capped summary, or `undefined` when stderr is blank.
 */
export declare function summarizeStderr(stderr: string, maxChars: number): string | undefined;
/**
 * Append a `hook/invoked` event naming the handler and hook point to `session`.
 * @param session - the session whose open turn records the event.
 * @param invocation - the invocation identity; an absent `matcher` is omitted from the payload.
 */
export declare function appendHookInvoked(session: Session, invocation: HookInvocation): void;
/**
 * Append the durable result paired with `hook/invoked`. The recorded decision
 * is the parsed decision, then `stop` for `continue:false`, else `pass`; stderr
 * is trimmed and capped, and an absent process exit stays omitted.
 * @param session - the session whose open turn records the event.
 * @param record - the outcome to record: the decoded output plus the summary cap and duration.
 */
export declare function appendHookResult(session: Session, record: HookResultRecord): void;
//# sourceMappingURL=events.d.ts.map