import type { TurnFailureReason } from '@genesislcap/foundation-ai';
/**
 * Event map for the AI activity bus.
 *
 * Declare-merge this interface to add your own event types:
 * ```ts
 * declare module '@genesislcap/ai-assistant' {
 *   interface AgenticActivityEvents {
 *     'grid-flash-rows': { gridId: string; rowIds: string[] };
 *   }
 * }
 * ```
 *
 * @beta
 */
export interface AgenticActivityEvents {
    /** Fired when the assistant begins a tool call. Contains the names of all active tools. */
    'halo-start': {
        toolNames: string[];
    };
    /** Fired when the assistant finishes all tool processing and returns to idle. */
    'halo-stop': undefined;
    /** Fired when the user clicks the expand button — moves assistant from bubble into layout. State lives in the session store, not in this event. */
    'chat-popout': undefined;
    /** Fired when the user clicks the collapse button — moves assistant from layout back to bubble. State lives in the session store, not in this event. */
    'chat-popin': undefined;
    /**
     * Fired immediately before the tool loop begins running for the current turn — after the busy
     * flag is set and the user message (if any) has been appended, but before the first
     * provider call. Pairs with {@link AgenticActivityEvents.'tool-loop-end'}.
     *
     * Boundary: this is the moment the assistant takes control from the user on the **main chat
     * prompt** to begin a turn. It is **not** fired when a tool handler temporarily hands a
     * widget to the user mid-loop (e.g. `requestInteraction` pausing a handler while a planning
     * widget is rendered) — those widget pauses happen inside the loop and the assistant is
     * still considered to own the turn.
     *
     * Fires from each `ChatDriver`'s `sendMessage` and `continueFromHistory`, so during a
     * multi-agent handoff orchestrated by `OrchestratingDriver` it fires once per agent
     * the orchestrator hands off to.
     *
     * Distinct from {@link AgenticActivityEvents.'halo-start'} — the halo event is keyed to
     * tool-call messages arriving in the stream (UI animation concern), not to the loop boundary
     * itself. Use this event for hooks tied to a turn beginning (telemetry, transient UI gates).
     */
    'tool-loop-start': undefined;
    /**
     * Fired when the tool loop completes for the current turn and control returns to the user
     * on the **main chat prompt** (i.e. the next free-form user message can now be accepted).
     *
     * Boundary: this is the moment the user regains control of the main chat input. It is
     * **not** fired when a tool handler hands a widget to the user mid-loop (e.g. while a
     * planning widget is awaiting a click) — widget pauses are still inside the loop, the
     * assistant still owns the turn, and the main chat input may be hidden during them. Wait
     * for this event when you need to know that the assistant is fully idle and the user can
     * type freely again.
     *
     * Emitted from the finally block of each `ChatDriver`'s `sendMessage` and
     * `continueFromHistory`, so a multi-agent handoff fires this event once per agent.
     *
     * Distinct from {@link AgenticActivityEvents.'halo-stop'} — the halo event tracks the
     * spinner animation lifecycle (which can flap mid-turn as tool calls resolve), whereas
     * this event is a one-shot per turn boundary. Use this for hooks tied to a turn ending
     * (telemetry flushes, post-turn workspace transitions, deferred state recomputation).
     *
     * The detail carries the turn's outcome (PTC-0): on a failure it is `{ failureReason }`
     * with the typed `TurnFailureReason`; on a clean completion, a user cancel, a
     * driver dispose, and an agent handoff the detail is `undefined` — the historical shape,
     * kept byte-identical so subscribers that only care about the boundary can keep ignoring
     * it. Structured-cloneable so it survives the cross-tab BroadcastChannel hop.
     */
    'tool-loop-end': {
        failureReason?: TurnFailureReason;
    } | undefined;
    /**
     * Fired when a tool handler hands a widget to the user mid-loop and parks awaiting it
     * (`requestInteraction`) — the turn is suspended between provider calls, with no request
     * in flight. Pairs with {@link AgenticActivityEvents.'interaction-resolved'}.
     *
     * This is the inverse boundary to {@link AgenticActivityEvents.'tool-loop-start'}: the
     * loop is running (still inside `tool-loop-start`/`tool-loop-end`) but is momentarily idle,
     * waiting on the user. Use it for hooks that are unsafe *while computing* but safe *while
     * parked* — e.g. enabling a control that must not change mid-request but is fine to change
     * during a long journey step. Tab-local (not forwarded cross-tab): the widget and its
     * waiting state belong to the tab that opened it.
     */
    'interaction-requested': undefined;
    /**
     * Fired when a parked widget interaction ends — by user completion, timeout, or
     * cancellation — just before the suspended tool handler resumes and the loop continues.
     * Pairs with {@link AgenticActivityEvents.'interaction-requested'}. After this the turn is
     * computing again (until `tool-loop-end`). Tab-local.
     */
    'interaction-resolved': undefined;
}
//# sourceMappingURL=ai-activity-channel.d.ts.map