TUI provider annotations

Spice Agent TUI publishes two explicit provider annotations:

• @UIShell for an exact agenttui.Shell provider or valid Go alias;
• @UIRenderer for an exact agenttui.Renderer provider or valid Go alias.

Both target exported package-level factory functions and require a canonical name. They also accept aliases, qualifiers, primary, fallback, and order. A bean cannot be both primary and fallback; identities must be unique, lowercase canonical values, and order is bounded from -1,000,000 through 1,000,000.

// @import { UIShell, UIRenderer } from "github.com/spice-framework/spice-agent-tui/annotation/ui"

// @UIShell(name="terminal", aliases=["interactive"], qualifiers=["primary-ui"], primary=true)
func NewTerminalShell(model Model, streams Streams) (
    agenttui.Shell,
    lifecycle.Cleanup,
    error,
)

// @UIRenderer(name="fixed", fallback=true, order=100)
func NewFixedRenderer(config RenderConfig) agenttui.Renderer

The consuming application’s root go.mod selects and authorizes the trusted native handler with standard Go tooling:

go get -tool github.com/spice-framework/spice-agent-tui/cmd/spice-agent-tui-annotations@<version>

The annotation tool path is github.com/spice-framework/spice-agent-tui/cmd/spice-agent-tui-annotations. It runs only as go tool <path> --spice-stdio and implements the public Spice v1alpha2 framed protocol. Normal analysis uses the already selected module graph and must not download or install anything in the background.

There is no type-name shortcut in either handler. The shared typed compiler publishes bounded facts for every function result: readable identity, canonical identity after alias removal, effective Go kind, and named origin. The handler requires result zero to be the exact public agenttui.Shell or agenttui.Renderer interface and accepts aliases through canonical identity. Defined wrapper interfaces, anonymous interfaces, concrete results, missing or malformed facts, and forged origins are rejected at the annotation position.

Supported output layouts are T, (T, error), (T, lifecycle.Cleanup), and (T, lifecycle.Cleanup, error). The handler validates the auxiliary identities but never executes the function or parses Declaration.TypeID. Constructor parameters and direct generated calls remain generic compiler responsibilities. Real-tool acceptance executes the pinned Spice CLI against alias-positive and wrapper/anonymous/concrete negative fixtures.

These annotations deliberately do not create a model, client session, input, output, shell, or renderer. They do not expose the internal presentation package, scan at runtime, mutate a container, or activate through dependency presence. Applications that want the library defaults must separately blank-import github.com/spice-framework/spice-agent-tui/autoconfigure and supply an exact agenttui.Session bean. The committed composition-proof target demonstrates that path through ordinary generated Go.