// Generated from types/*.ts — do not edit.
// Regenerate with: npm run generate:typescript

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

import type {
  ConfigSchema,
  JsonPrimitive,
  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
 * @exhaustive
 */
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[];
  /**
   * Static capabilities the agent advertises about itself. Clients use these
   * to gate features (multi-chat, fork) instead of switching on the provider
   * id.
   */
  capabilities?: AgentCapabilities;
}

/**
 * Static capabilities an {@link AgentInfo} advertises. Modelled after MCP
 * capabilities: each field is opt-in and its presence (an empty object `{}`)
 * signals support, while absence means the feature is unsupported and the
 * corresponding client commands MUST NOT be used. Sub-fields carry
 * per-capability options.
 *
 * @category Root State
 */
export interface AgentCapabilities {
  /**
   * The agent can host more than one concurrent chat per session. When absent,
   * clients MUST NOT call `createChat` to open chats beyond the default one the
   * session starts with. An empty object `{}` advertises multi-chat without
   * source-based creation; set {@link MultipleChatsCapability.fork} or
   * {@link MultipleChatsCapability.sideChat} to allow the corresponding mode.
   */
  multipleChats?: MultipleChatsCapability;
  /**
   * The session's agent can be granted tool access to more than one working
   * directory. The directories are treated as equal peers except where the
   * agent advertises a protected primary-slot option (some backends pin or
   * replace their first directory as a process root).
   *
   * When absent, clients MUST NOT mutate a session's or chat's working-directory
   * set and MUST NOT set more than one entry in
   * {@link CreateSessionParams.workingDirectories}.
   */
  multipleWorkingDirectories?: MultipleWorkingDirectoriesCapability;
}

/**
 * Options for the {@link AgentCapabilities.multipleChats} capability.
 *
 * @category Root State
 */
export interface MultipleChatsCapability {
  /**
   * The agent can fork a chat from a specific turn. When absent or `false`,
   * clients MUST NOT pass a {@link ChatSource} with `kind: "fork"` to
   * `createChat`.
   * Forking always implies multi-chat support.
   */
  fork?: boolean;
  /**
   * The agent can create a side chat from a specific turn. When absent or
   * `false`, clients MUST NOT pass a {@link ChatSource} with
   * `kind: "sideChat"` to `createChat`.
   *
   * A side chat receives the source turn as context without copying the source
   * transcript into its own visible history. The source is identified by a
   * stable `turnId`, which the host resolves against the source chat's current
   * `activeTurn` or retained history. When it names the current active turn,
   * the host snapshots the available partial assistant response at creation
   * time. Side-chat support always implies multi-chat support.
   */
  sideChat?: boolean;
}

/**
 * Options for the {@link AgentCapabilities.multipleWorkingDirectories} capability.
 *
 * @category Root State
 */
export interface MultipleWorkingDirectoriesCapability {
  /**
   * The agent's **first** working directory (index `0` of
   * {@link CreateSessionParams.workingDirectories}) is an immutable primary:
   * its URI is fixed for the lifetime of the session — clients MUST NOT remove,
   * reorder, or replace it. Additional directories after it remain equal peers
   * that can be added and removed freely. When
   * {@link primaryReplacement} is also `true`, clients that recognize that
   * capability MUST instead treat the primary as protected and replaceable.
   *
   * Advertised by backends whose agent process is rooted at a single directory
   * that cannot change once the session has started. A backend MAY also
   * advertise this with {@link primaryReplacement} for compatibility with
   * clients that do not recognize the newer capability: those clients retain
   * the safe immutable-primary behavior, while newer clients allow only the
   * targeted replacement action. When both are absent or `false`, all
   * directories are equal peers.
   */
  immutablePrimary?: boolean;
  /**
   * The agent's first working-directory slot (index `0`) is a protected primary
   * whose URI can be atomically replaced with
   * `session/workingDirectoryReplaced`. Clients MUST NOT remove that slot with
   * generic membership actions; additional directories remain equal peers.
   *
   * Backends use this when their cwd-bearing directory can move during a
   * session. It MAY be `true` together with {@link immutablePrimary}; this
   * preserves the immutable-primary guarantee for older clients that do not
   * recognize this capability. Clients that recognize this capability MUST
   * allow a targeted replacement even when `immutablePrimary` is also `true`.
   */
  primaryReplacement?: boolean;
}

/**
 * @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;
  /** Maximum number of output tokens the model can generate */
  maxOutputTokens?: number;
  /** Maximum number of prompt (input) tokens the model accepts */
  maxPromptTokens?: 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. Values are JSON primitives: most
   * pickers produce strings, but some (e.g. a numeric context-size picker)
   * produce numbers or booleans, which are carried through as-is.
   */
  config?: Record<string, JsonPrimitive>;
}

// ─── 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>;
}