/**
 * Shared type declarations for the grounding subsystem.
 *
 * Pure JSDoc — no runtime emission. Imported via `@typedef` references
 * from adapter / metrics / registry files so callers get type
 * inference without a TypeScript build step.
 */

/**
 * @typedef {Object} Point
 * @property {number} x
 * @property {number} y
 */

/**
 * @typedef {Object} Rect
 * @property {number} x      - left edge
 * @property {number} y      - top edge
 * @property {number} width
 * @property {number} height
 */

/**
 * @typedef {Object} ToolDef
 * @description OpenAI-shaped function-tool definition that the
 *              grounding model may invoke via `tool_calls`. Adapters
 *              translate this to their provider's wire shape.
 * @property {'function'} type
 * @property {{ name: string, description: string, parameters: object }} function
 */

/**
 * @typedef {Object} ToolCall
 * @property {string} id
 * @property {'function'} type
 * @property {{ name: string, arguments: string }} function - arguments is a JSON string
 */

/**
 * @typedef {Object} GroundOptions
 * @property {Buffer} screenshot      - PNG bytes of the (sub)screen
 * @property {string} intent          - natural-language description of the goal
 * @property {ToolDef[]} [tools]      - if set, model may emit tool_calls
 * @property {Object} [knobs]         - adapter-specific tuning (matches supportedKnobs())
 * @property {number} [timeoutMs]     - per-call ceiling; overrides adapter default
 * @property {string} [idempotencyKey]- caller-supplied for billing dedup
 * @property {{width:number,height:number}} [imageSize] - optional explicit dims
 *                                                       (some models ground better
 *                                                       when told the image size)
 */

/**
 * @typedef {Object} GroundUsage
 * @property {number} input_tokens
 * @property {number} output_tokens
 * @property {number} [reasoning_tokens]
 */

/**
 * @typedef {Object} GroundResult
 * @property {string} answer                - raw text answer from the model
 * @property {ToolCall[]} [tool_calls]      - if tools were provided + used
 * @property {Point} [coords]               - parsed from `answer` when no tool_calls
 * @property {string} [reasoning_content]   - visible reasoning trace (optional)
 * @property {GroundUsage} usage
 * @property {number} elapsed_ms
 * @property {string} modelId               - which adapter handled this call
 * @property {Object} [raw]                 - provider response (audit only;
 *                                            should NOT be persisted long-term)
 */

/**
 * @typedef {Object} KnobOption
 * @property {string|number} value
 * @property {string} [label]
 */

/**
 * @typedef {Object} KnobDef
 * @property {string} id             - matches a key in GroundOptions.knobs
 * @property {string} label
 * @property {'enum'|'number'|'boolean'|'string'} type
 * @property {*} default
 * @property {KnobOption[]} [options]- for enum type
 * @property {[number, number]} [range] - for number type (inclusive)
 * @property {string} [doc]
 * @property {boolean} [advanced]    - hide behind a "show advanced" toggle
 */

/**
 * @typedef {Object} Capabilities
 * @property {boolean} pixelGrounding      - can return coords from a screenshot
 * @property {boolean} toolCalling         - supports OpenAI-style tool_calls
 * @property {boolean} multiTurnLoop       - drives its own multi-step loop
 * @property {boolean} visionInput
 * @property {number} maxImagePixels       - rough budget; 0 = unknown
 * @property {number} typicalLatencyMs     - p50 in default config
 * @property {number} typicalCostPerCallUSD- p50 in default config
 */

/**
 * @typedef {Object} ValidationResult
 * @property {boolean} valid
 * @property {Object.<string,string>} errors - {knobId: message}
 */

// No runtime exports — this file is purely JSDoc-driven.
export {};
