/**
 * Root State Types — Global state exposed on the `ahp-root://` channel.
 *
 * @module channels-root/state
 */

import type {
  ConfigSchema,
  ProtectedResourceMetadata,
} from '../common/state.js';
import type { TerminalInfo } from '../channels-terminal/state.js';
import type { Customization } from '../channels-session/state.js';

// ─── Root State ──────────────────────────────────────────────────────────────

/**
 * Policy configuration state for a model.
 *
 * @category Root State
 */
export const enum PolicyState {
  Enabled = 'enabled',
  Disabled = 'disabled',
  Unconfigured = 'unconfigured',
}

/**
 * Global state shared with every client subscribed to `ahp-root://`.
 *
 * @category Root State
 */
export interface RootState {
  /** Available agent backends and their models */
  agents: AgentInfo[];
  /** Number of active (non-disposed) sessions on the server */
  activeSessions?: number;
  /** Known terminals on the server. Subscribe to individual terminal URIs for full state. */
  terminals?: TerminalInfo[];
  /** Agent host configuration schema and current values */
  config?: RootConfigState;
  /**
   * Additional implementation-defined metadata about the agent host itself.
   *
   * Clients MAY look for well-known keys here to provide enhanced UI.
   */
  _meta?: Record<string, unknown>;
}

/**
 * @category Root State
 */
export interface AgentInfo {
  /** Agent provider ID (e.g. `'copilot'`) */
  provider: string;
  /** Human-readable name */
  displayName: string;
  /** Description string */
  description: string;
  /** Available models for this agent */
  models: SessionModelInfo[];
  /**
   * Protected resources this agent requires authentication for.
   *
   * Each entry describes an OAuth 2.0 protected resource using
   * [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) semantics.
   * Clients should obtain tokens from the declared `authorization_servers`
   * and push them via the `authenticate` command before creating sessions
   * with this agent.
   *
   * @see {@link /specification/authentication | Authentication}
   */
  protectedResources?: ProtectedResourceMetadata[];
  /**
   * Customizations associated with this agent.
   *
   * Either container customizations —
   * {@link PluginCustomization | `PluginCustomization`} entries the agent
   * bundles, plus {@link DirectoryCustomization | `DirectoryCustomization`}
   * entries it watches in any workspace it's used with — or top-level
   * {@link McpServerCustomization | `McpServerCustomization`} entries
   * the agent host declares directly. When a session is created with
   * this agent, these entries are augmented (e.g. directory URIs are
   * resolved against the workspace, children are parsed) and propagated
   * into the session's `customizations` list.
   */
  customizations?: Customization[];
}

/**
 * @category Root State
 */
export interface SessionModelInfo {
  /** Model identifier */
  id: string;
  /** Provider this model belongs to */
  provider: string;
  /** Human-readable model name */
  name: string;
  /** Maximum context window size */
  maxContextWindow?: number;
  /** Whether the model supports vision */
  supportsVision?: boolean;
  /** Policy configuration state */
  policyState?: PolicyState;
  /**
   * Configuration schema describing model-specific options (e.g. thinking
   * level). Clients present this as a form and pass the resolved values in
   * {@link ModelSelection.config} when creating or changing sessions.
   */
  configSchema?: ConfigSchema;
  /**
   * Additional provider-specific metadata for this model.
   *
   * Clients MAY look for well-known keys here to provide enhanced UI.
   * For example, a `pricing` key may carry model pricing metadata.
   */
  _meta?: Record<string, unknown>;
}

/**
 * A model selection: the chosen model ID together with any model-specific
 * configuration values whose keys correspond to the model's
 * {@link SessionModelInfo.configSchema}.
 *
 * @category Root State
 */
export interface ModelSelection {
  /** Model identifier */
  id: string;
  /** Model-specific configuration values */
  config?: Record<string, string>;
}

// ─── Root Config Types ───────────────────────────────────────────────────────

/**
 * Live agent-host configuration metadata.
 *
 * The schema describes the available configuration properties and the values
 * contain the current value for each resolved property.
 *
 * @category Root State
 */
export interface RootConfigState {
  /** JSON Schema describing available configuration properties */
  schema: ConfigSchema;
  /** Current configuration values */
  values: Record<string, unknown>;
}
