/**
 * pause — runner-level pause/resume primitives.
 *
 * Pattern: Control-flow exception (PauseRequest) + typed outcome (RunnerPauseOutcome).
 * Role:    core/ layer. Bridges footprintjs.s pause signal into the agentfootprint
 *          Runner contract: tools call `pauseHere(data)` to raise a pause
 *          intent; runners detect the paused executor result and return a
 *          `RunnerPauseOutcome` instead of `TOut`. Consumers call
 *          `runner.resume(checkpoint, input)` to continue.
 * Emits:   N/A (types + helpers only). Event emission happens in RunnerBase.
 *
 * Why a control-flow "throw": tool.execute(args, ctx) doesn't receive the
 * typed scope, so it cannot call `scope.$pause()` directly. A thrown
 * `PauseRequest` is caught inside the Agent's tool-call stage, which then
 * forwards the pause into the flowchart via `scope.$pause()`. This keeps
 * the tool API clean (tools are pure-ish) while still supporting pause.
 */
import type { FlowchartCheckpoint } from 'footprintjs';
import type { CheckInRequest } from './checkin.js';
/**
 * Outcome returned by `runner.run()` / `runner.resume()` when execution
 * has paused mid-flow. The shape mirrors footprintjs's `PausedResult` but
 * surfaces `pauseData` as a first-class field for consumers who don't
 * want to reach into the checkpoint.
 */
export interface RunnerPauseOutcome {
    readonly paused: true;
    /** Serializable checkpoint — store anywhere (Redis, Postgres, localStorage). */
    readonly checkpoint: FlowchartCheckpoint;
    /** Data passed to `scope.$pause()` / `pauseHere()`. Consumer-typed. */
    readonly pauseData: unknown;
    /**
     * Present ONLY when this pause is an evidence-carrying check-in (a tool
     * declared `checkIn`). Carries the typed ask + evidence pack. Absent for
     * plain `askHuman` / `pauseHere` pauses — that's the clean discriminant
     * between the two pause kinds. Resume with a `CheckInDecision`
     * (`checkInApproved` / `checkInDeclined`).
     */
    readonly checkIn?: CheckInRequest;
}
/** Type guard — discriminates `RunnerPauseOutcome` from a normal `TOut`. */
export declare function isPaused<T>(result: T | RunnerPauseOutcome): result is RunnerPauseOutcome;
/**
 * Type guard — is this a check-in pause (evidence-carrying human consent),
 * as opposed to a plain `askHuman` pause? Narrows `checkIn` to present.
 *
 * @example
 *   const out = await agent.run({ message });
 *   if (isCheckInPause(out)) {
 *     showToHuman(out.checkIn.evidence);       // the receipts
 *     const decision = checkInApproved({ by: 'alice' });
 *     await agent.resume(out.checkpoint, decision);
 *   }
 */
export declare function isCheckInPause(result: unknown): result is RunnerPauseOutcome & {
    readonly checkIn: CheckInRequest;
};
/**
 * Control-flow error raised by `pauseHere()` inside a tool's `execute()`.
 * Caught by the Agent's tool-call stage, which forwards to `scope.$pause()`.
 * Never propagates to the consumer.
 */
export declare class PauseRequest extends Error {
    readonly data: unknown;
    constructor(data: unknown);
}
/**
 * Called from inside a tool's `execute()` to request a pause. Throws a
 * `PauseRequest` that the Agent catches and forwards to the flowchart.
 *
 * @example
 *   const approveTool: Tool<{ action: string }, string> = {
 *     schema: { name: 'approve', description: 'Ask human', inputSchema: {...} },
 *     execute: async (args) => {
 *       pauseHere({ question: `Approve ${args.action}?`, risk: 'high' });
 *       return ''; // unreachable — pauseHere always throws
 *     },
 *   };
 */
export declare function pauseHere(data: unknown): never;
/** Type guard for a thrown `PauseRequest`. */
export declare function isPauseRequest(err: unknown): err is PauseRequest;
/**
 * Ergonomic alias for `pauseHere(data)` — the human-in-the-loop name.
 *
 * `pauseHere` describes the mechanism (control-flow throw); `askHuman`
 * describes the intent (ask a person to decide). Both work identically.
 *
 * @example
 *   const approveRefund: Tool<{ amount: number }, string> = {
 *     schema: { name: 'approve_refund', description: '...', inputSchema: {...} },
 *     execute: async ({ amount }) => {
 *       if (amount > 1000) askHuman({ question: `Approve $${amount}?` });
 *       return 'auto-approved';
 *     },
 *   };
 */
export declare const askHuman: typeof pauseHere;