@aihu/agent

function getAgentMetadata(tag: string): AgentMetadata | undefined

Return the registered `AgentMetadata` for `tag`, or `undefined` if no entry exists.

function getAllAgentMetadata(): AgentMetadata[]

Return all registered `AgentMetadata` entries as an array.

function registerAgentMetadata(meta: AgentMetadata): void

Insert or overwrite the registry entry for `meta.tag`.

interface ActionParamsSchema {
  properties: Record<string, unknown>
  required: string[]
}

The MCP `inputSchema` fragment for an action's parameters, DERIVED by the compiler from the `$action` handler's own signature (DE5).

interface ActionSchema {
  returns: Record<string, InputSchema>
  /**
   * Human-readable description of what the action does, sourced from the
   * `describe:` key on the component's `$action` entry. Surfaced as the MCP
   * tool description — this is the text an LLM reads when deciding whether to
   * call the tool, so its absence degrades tool selection, not just docs.
   */
  describe?: string
  /**
   * Derived MCP parameter schema (DE5). Present when the compiler could model
   * the handler signature; absent when it could not (an unparseable handler or
   * an unnameable destructuring parameter), in which case the server falls back
   * to the legacy positional `args: { type: 'array' }` schema for this tool.
   */
  params?: ActionParamsSchema
}

Schema for a single callable action on a component.

interface AgentMetadata {
  /** The custom-element tag name this metadata describes. */
  tag: string
  /** MCP prompt/description — human-readable summary of what this element does. */
  describes?: string
  /** MCP resources — names mapped to human-readable descriptions of reactive state. */
  state?: Record<string, string>
  /** MCP tools — action names mapped to typed schemas. */
  actions?: Record<string, ActionSchema>
  /**
   * Resolved `extract:` governance policy (GX #468) — identical to the
   * `"extract"` member of this component's agent-meta sidecar. Absent only in
   * pre-GX compiled output or hand-authored metadata; consumers treat absence
   * as the resolved default posture (`call: 'anonymous'`).
   */
  extract?: ExtractPolicy
  /** Unknown fields are preserved, not rejected (spec §9.1). */
  [key: string]: unknown
}

Static metadata describing a `<custom-tag>` component for AI-agent consumption.

interface ExtractPolicy {
  /** `read` (crawl-visibility) axis — GX spec §2.1. */
  read?: 'all' | 'agents' | 'search' | 'none' | 'verified' | 'human' | ExtractScopePolicy
  /** `call` (agent-callability) axis — GX spec §2.1. */
  call?: 'none' | 'anonymous' | 'verified' | ExtractScopePolicy
}

The resolved `extract:` governance policy for a component surface (GX #468).

interface ExtractScopePolicy {
  scope: string
}

The `{ scope: '<name>' }` value shape shared by both `extract` axes (GX spec §3 row 6): the scope is part of the value by construction — "gated without a scope" is unrepresentable.

interface InputSchema {
  type: 'string' | 'number' | 'boolean' | 'enum'
  values?: string[]
  default?: string
}

Schema for a single input field exposed by a component or action return.