/**
 * Capability dispatch helpers for bridge drivers.
 *
 * The runner builds a {@link BridgeCapabilityHooks} bundle from its
 * `CapabilityRegistry` and threads it through `AgentConfig.capabilities`.
 * Drivers consume the bundle via these helpers without taking a runtime
 * dependency on `@skaile/workspaces/runner` (which would create a circular dep).
 *
 * Three behaviours are layered into a single dispatch path:
 *
 * 1. **Standard tool call** — the LLM invokes a capability; the bridge calls
 *    `hooks.invoke()`, awaits the result, and returns it to the LLM.
 * 2. **Fire-and-forget** — when the resolved Capability has `fireAndForget`
 *    set, the bridge resolves to `{}` immediately and runs the handler in
 *    the background. Background errors are logged but never surfaced to the
 *    LLM since the call is already settled.
 * 3. **Render capability** — when the resolved Capability has a non-undefined
 *    `render`, the bridge emits `RenderInvokedEvent` to the runner via
 *    `hooks.emitRender` and (when `render.fallback` is set) a parallel text
 *    event via `hooks.emitText` with simple `{{prop}}` substitution. The
 *    placeholder convention follows the v2 spec — top-level keys of `props`
 *    only, with optional dotted-path traversal (`{{user.name}}`). The legacy
 *    AAP `{{props.x}}` form was retired in Phase 6.
 *
 * @category Capabilities
 * @since 2.0.0
 */
import type { Capability } from "@skaile/workspaces/types";
import type { BridgeCapabilityHooks } from "./types.js";
/**
 * Result of a capability dispatch returned by {@link dispatchCapability}.
 *
 * The bridge feeds `{ result }` back to the LLM tool-use response. For
 * fire-and-forget capabilities `result` is always `{}` and `background` is `true`.
 *
 * @docLink packages/bridge/concepts#capability-dispatch-result
 */
export interface CapabilityDispatchResult {
    /** Value returned to the LLM. `{}` for fire-and-forget capabilities. */
    result: unknown;
    /** True when the handler is still running in the background (fire-and-forget). */
    background: boolean;
}
/**
 * Run a capability invocation through the runner-provided hooks, applying
 * render-event emission and fire-and-forget short-circuit.
 *
 * The result is always shaped for direct return to the LLM. For
 * fire-and-forget capabilities the background promise is fired and any error
 * is logged through `onBackgroundError` (defaulting to a no-op). For all
 * other capabilities the handler is awaited; errors propagate as a rejection
 * so the driver can surface them as tool errors.
 *
 * @param hooks - Capability dispatch bundle from `AgentConfig.capabilities`.
 * @param callId - Correlation ID for the tool-use invocation (used in render events).
 * @param name - Registered capability name.
 * @param input - Raw tool input from the LLM.
 * @param onBackgroundError - Optional error handler for fire-and-forget failures.
 * @returns Resolved dispatch result with the LLM-facing value and background flag.
 * @docLink packages/bridge/concepts#dispatch-capability
 */
export declare function dispatchCapability(hooks: BridgeCapabilityHooks, callId: string, name: string, input: unknown, onBackgroundError?: (err: unknown) => void, signal?: AbortSignal): Promise<CapabilityDispatchResult>;
/**
 * Substitute `{{prop}}` placeholders inside a fallback template using the
 * input record. Top-level keys of `props` resolve directly
 * (`{{name}}` → `props.name`); dotted paths traverse nested records
 * (`{{user.name}}` → `props.user.name`). Missing keys collapse to an empty
 * string; non-record inputs collapse all placeholders.
 *
 * The convention is fixed by the v2 spec (§1, `RenderSpec.fallback`). The
 * legacy AAP form `{{props.x}}` is no longer accepted — author fallbacks
 * with bare keys.
 *
 * Intentionally minimal — full template engines belong in the platform's
 * render layer, not the bridge.
 *
 * @param template - Fallback string from `RenderSpec.fallback` with `{{key}}` placeholders.
 * @param input - LLM tool input object; non-object values collapse all placeholders.
 * @returns Template with all resolvable placeholders replaced.
 * @docLink packages/bridge/concepts#render-fallback
 */
export declare function renderFallback(template: string, input: unknown): string;
/**
 * Filter a capability list to those marked as render-capable (having a `render` spec).
 *
 * Used by drivers that emit a separate render manifest at registration time.
 * Currently unused in production drivers; reserved for future phases.
 *
 * @param caps - Full capability list to filter.
 * @returns Subset of capabilities with a non-undefined `render` property.
 * @docLink packages/bridge/concepts#filter-render-capabilities
 */
export declare function filterRenderCapabilities(caps: Capability[]): Capability[];
//# sourceMappingURL=capability-dispatch.d.ts.map