/**
 * Session stimulus bus — generic trailing-edge coalescing turn driver.
 *
 * Connectors that observe state changes (FlowAdapter, future alert/inbox/
 * file-watch connectors) call `bus.signal(connectorId, { promptFragment, meta })`
 * to request that the agent be woken with a fresh turn. Multiple signals from
 * the same connector arriving within `coalesceMs` are folded into one turn,
 * with their `promptFragment`s concatenated by `\n\n` and their `meta` objects
 * collected into an array.
 *
 * Per-`connectorId` queues — concurrent connectors NEVER coalesce together;
 * each runs its own pending timer and turn pipeline.
 *
 * If `signal()` is called for a connector whose driveTurn is already in flight,
 * the new signal queues for the next cycle (a fresh timer starts only after
 * the in-flight turn settles).
 *
 * Distinct from `refresh-flag-dispatcher.ts`'s leading-edge debounce: that one
 * fires immediately and drops within a 2 s window. The stimulus bus is trailing-
 * edge collapse with a returned promise, so callers can `await` completion of
 * the turn that drained their signal.
 *
 * @docLink runner#session-stimulus-bus
 * @since 2.2.0
 */
import type { Logger } from "@skaile/workspaces/types";
/**
 * One stimulus from a connector. The bus collapses contiguous signals from the
 * same connector into a single turn whose prompt is built by joining the
 * `promptFragment`s with `\n\n`.
 */
export interface StimulusSignal {
    /** Fragment the connector wants prepended to the next turn prompt. */
    promptFragment: string;
    /** Optional event metadata for tracing. Connector-defined. */
    meta?: Record<string, unknown>;
    /**
     * Trailing-edge coalesce window — multiple signals from the same connector
     * arriving within this many ms are folded into one turn with their
     * fragments concatenated. Default: 50 ms (a tick to let near-simultaneous
     * signals settle without perceptible delay).
     */
    coalesceMs?: number;
}
/**
 * Public surface returned by `createSessionStimulusBus`. Connectors hold a
 * reference to this and call `signal(...)` whenever they want to wake the
 * agent.
 */
export interface SessionStimulusBus {
    /**
     * Request a turn kick for `connectorId`. Resolves once the resulting turn
     * has drained (the supplied `driveTurn` resolved). Multiple parallel calls
     * within `coalesceMs` collapse into one turn and share a single resolution.
     */
    signal(connectorId: string, sig: StimulusSignal): Promise<void>;
}
/**
 * Drives one agent turn given a concatenated prompt fragment. The runner
 * supplies this when constructing the bus — typically wraps `driver.prompt`
 * + waits for `agent_end`. The bus calls it with all coalesced fragments
 * joined by newline.
 */
export type TurnDriver = (promptFragment: string, batchedMeta: Array<Record<string, unknown>>) => Promise<void>;
export interface CreateStimulusBusOptions {
    driveTurn: TurnDriver;
    /** Default coalesce window when a signal omits its own. */
    defaultCoalesceMs?: number;
    log?: Logger;
}
/** Default coalesce window — kept consistent with the spec's stated default. */
export declare const DEFAULT_COALESCE_MS = 50;
/**
 * Construct a fresh stimulus bus. The caller (typically `serve.ts` or
 * `run-flow.ts`) provides `driveTurn`, which kicks one agent turn given a
 * joined prompt + batched meta, and resolves once the turn drains.
 */
export declare function createSessionStimulusBus(opts: CreateStimulusBusOptions): SessionStimulusBus;
//# sourceMappingURL=session-stimulus.d.ts.map