/**
 * Root Channel Commands — `listSessions`, `resolveSessionConfig`, and
 * `sessionConfigCompletions`. These commands target `ahp-root://` even
 * though they describe per-session metadata.
 *
 * @module channels-root/commands
 */

import type { URI } from '../common/state.js';
import type { BaseParams } from '../common/commands.js';
import type { SessionSummary, SessionConfigSchema } from '../channels-session/state.js';

// Re-export schema types so the legacy `commands.ts` aggregator continues to
// expose them from the same import path.
export type { ConfigPropertySchema, ConfigSchema } from '../common/state.js';
export type { SessionConfigPropertySchema, SessionConfigSchema } from '../channels-session/state.js';

// ─── listSessions ────────────────────────────────────────────────────────────

/**
 * Returns a list of session summaries. Used to populate session lists and sidebars.
 *
 * The session list is **not** part of the state tree because it can be arbitrarily
 * large. Clients fetch it imperatively and maintain a local cache updated by
 * `root/sessionAdded` and `root/sessionRemoved` notifications.
 *
 * @category Commands
 * @method listSessions
 * @direction Client → Server
 * @messageType Request
 * @version 1
 */
export interface ListSessionsParams extends BaseParams {
  channel: 'ahp-root://';
  /** Optional filter criteria */
  filter?: object;
}

/** Result of the `listSessions` command. */
export interface ListSessionsResult {
  /** The list of session summaries. */
  items: SessionSummary[];
}

// ─── resolveSessionConfig ────────────────────────────────────────────────────

/**
 * Iteratively resolves the session configuration schema. The client sends the
 * current partial session config and any user-filled metadata values. The server
 * returns a property schema describing what additional metadata is needed,
 * contextual to the current selections.
 *
 * The client calls this command whenever the user changes a significant input
 * (e.g. picks a working directory, toggles a property). Each response returns
 * the full current property set (not a delta). The returned `values` contain
 * server-resolved defaults to pass to `createSession`.
 *
 * @category Commands
 * @method resolveSessionConfig
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Step 1: Client picks a working directory
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 5, "method": "resolveSessionConfig",
 *   "params": { "workingDirectory": "file:///home/user/my-project" } }
 *
 * // Server → Client (git repo detected, offers worktree option)
 * { "jsonrpc": "2.0", "id": 5, "result": {
 *   "schema": {
 *     "type": "object",
 *     "properties": {
 *       "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] }
 *     }
 *   },
 *   "values": {}
 * }}
 *
 * // Step 2: User enables worktree
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 6, "method": "resolveSessionConfig",
 *   "params": { "workingDirectory": "file:///home/user/my-project",
 *               "config": { "target": "worktree" } } }
 *
 * // Server → Client (now requires branch selection)
 * { "jsonrpc": "2.0", "id": 6, "result": {
 *   "schema": {
 *     "type": "object",
 *     "properties": {
 *       "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] },
 *       "baseBranch": { "type": "string", "title": "Base Branch",
 *                       "enum": ["main", "develop"],
 *                       "enumLabels": ["main", "develop"] }
 *     },
 *     "required": ["baseBranch"]
 *   },
 *   "values": { "target": "worktree" }
 * }}
 * ```
 */
export interface ResolveSessionConfigParams extends BaseParams {
  channel: 'ahp-root://';
  /** Agent provider ID */
  provider?: string;
  /** Working directory for the session */
  workingDirectory?: URI;
  /** Current user-filled configuration values */
  config?: Record<string, unknown>;
}

/**
 * Result of the `resolveSessionConfig` command.
 */
export interface ResolveSessionConfigResult {
  /** JSON Schema describing available configuration properties given the current context */
  schema: SessionConfigSchema;
  /** Current configuration values (echoed back with server-resolved defaults applied) */
  values: Record<string, unknown>;
}

// ─── sessionConfigCompletions ────────────────────────────────────────────────

/**
 * A single value item returned by `sessionConfigCompletions`.
 *
 * @category Commands
 */
export interface SessionConfigValueItem {
  /** The value to store in config */
  value: string;
  /** Human-readable display label */
  label: string;
  /** Optional secondary description */
  description?: string;
}

/**
 * Queries the server for allowed values of a dynamic session config property.
 *
 * Used when a property in the schema returned by `resolveSessionConfig` has
 * `enumDynamic: true`. The client sends a search query and receives matching
 * values with display metadata.
 *
 * @category Commands
 * @method sessionConfigCompletions
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Client → Server (user types "ma" in branch picker)
 * { "jsonrpc": "2.0", "id": 7, "method": "sessionConfigCompletions",
 *   "params": { "workingDirectory": "file:///home/user/my-project",
 *               "config": { "target": "worktree" },
 *               "property": "baseBranch", "query": "ma" } }
 *
 * // Server → Client
 * { "jsonrpc": "2.0", "id": 7, "result": {
 *   "items": [
 *     { "value": "main", "label": "main", "icon": "git-branch" },
 *     { "value": "main-v2", "label": "main-v2", "icon": "git-branch" }
 *   ]
 * }}
 * ```
 */
export interface SessionConfigCompletionsParams extends BaseParams {
  channel: 'ahp-root://';
  /** Agent provider ID */
  provider?: string;
  /** Working directory for the session */
  workingDirectory?: URI;
  /** Current user-filled configuration values (provides context for the query) */
  config?: Record<string, unknown>;
  /** Property id from the schema to query values for */
  property: string;
  /** Search filter text (empty or omitted returns default/recent values) */
  query?: string;
}

/**
 * Result of the `sessionConfigCompletions` command.
 */
export interface SessionConfigCompletionsResult {
  /** Matching value items */
  items: SessionConfigValueItem[];
}
