Providers — Query

Query providers resolve query_* tags from user input — CLI positional args, clipboard, or IDE plugin data. They are resolved once at pipeline startup (before the engine loop) and stored in input_tags.

Contract

• Each query_* provider receives the raw positional argument (if any).
• Non-empty result wins. Empty input → "" — the val candidate is skipped and the next candidate for the same name is tried.
• Exception: query_image returns Err if the input is not a valid image (hard failure, not empty).
• Empty query value without a when guard is a startup error (ambiguous input). Add when: 'is:empty:not' to explicitly handle missing input.

Usage in a val candidate:

val:
  - name: content
    data: query_raw
    when: 'is:path'
    mods: 'fetch|text'
  - name: content
    data: query_raw
    fail: 'is:empty:not'

Tags

query_raw — raw input, no validation

No type checking, no path resolution. Use when the input might be text, a path, a URL — anything.

query_prompt — interactive prompt marker

This is a presence marker, not a data provider. When query_prompt appears in any val chain and the query slot is empty, the CLI triggers an interactive terminal prompt. In IDE mode, the plugin opens an input dialog.

The prompt itself fires at a fixed early point in the flow — not during val resolution.

query_clipboard — combined clipboard

Reads clipboard content trying each type in order. Token-limited to the largest num_ctx across all cluster nodes (prevents oversized clipboard input from blowing context windows).

query_clipboard_text — clipboard text

query_clipboard_path — clipboard file paths

Multiple paths are newline-separated.

query_clipboard_image — clipboard image

query_file_path — file path from input

Resolves the positional arg to an absolute path. Supports file:// URI format from IDE plugins. Returns "" if no file exists at the path — this makes the when: 'is:empty:not' pattern work for conditional file-based candidates.

query_project_path — project root path

Walks up from the input path looking for a project marker, then returns the root directory. Recognized markers:

.git, .hg, Cargo.toml, package.json, go.mod, pom.xml, build.gradle, .idea

Stops at the home directory or filesystem root. Returns "" if no marker is found.

query_line — first line of input

Useful for single-line IDE inputs (cursor line, selection first line).

query_image — image input

Accepts three input forms:

• URL (http:// / https://) → downloads, encodes to base64.
• File path → reads file, encodes to base64.
• Base64 string → decoded and validated.

Always validates that the bytes form a real image. Invalid input is a hard error — use a when guard or a fallback candidate to handle missing images gracefully.

Resolution flow

Query providers are resolved early, before the engine loop:

1. apply_args() — CLI flags → input_tags.
2. apply_query_tags() — each query_* in val candidates → input_tags.
3. validate_query_tags() — reject empty query values without a when guard.

After this, input_tags is frozen and the engine begins resolving actions.

CLI vs IDE

The IDE plugin fills the query slot based on the api.input field in the YAML manifest — see IDE Plugin.