/**
 * Session Channel Commands — `createSession`, `disposeSession`, `fetchTurns`,
 * and `completions`. Most target a specific `ahp-session:` URI.
 *
 * @module channels-session/commands
 */
import type { URI } from '../common/state.js';
import type { BaseParams } from '../common/commands.js';
import type { SessionActiveClient } from './state.js';
import type { MessageAttachment } from '../channels-chat/state.js';
/**
 * Creates a new session with the specified agent provider.
 *
 * If the session URI already exists, the server MUST return an error with code
 * `-32003` (`SessionAlreadyExists`).
 *
 * After creation, the client should subscribe to the session URI to receive state
 * updates. The server also broadcasts a `root/sessionAdded` notification to all
 * clients.
 *
 * @category Commands
 * @method createSession
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 2, "method": "createSession",
 *   "params": { "channel": "ahp-session:/<uuid>", "provider": "copilot" } }
 *
 * // Server → Client (success)
 * { "jsonrpc": "2.0", "id": 2, "result": null }
 *
 * // Server → Client (failure — provider not found)
 * { "jsonrpc": "2.0", "id": 2, "error": { "code": -32002, "message": "No agent for provider" } }
 *
 * // Server → Client (failure — session already exists)
 * { "jsonrpc": "2.0", "id": 2, "error": { "code": -32003, "message": "Session already exists" } }
 * ```
 */
export interface CreateSessionParams extends BaseParams {
    /** Session URI (client-chosen, e.g. `ahp-session:/<uuid>`) */
    channel: URI;
    /** Agent provider ID */
    provider?: string;
    /**
     * The working directories the session's agent is granted tool access to.
     * A session may span multiple directories; they are equal peers except when
     * the agent advertises a protected-primary capability. An
     * {@link MultipleWorkingDirectoriesCapability.immutablePrimary | immutable
     * primary} is fixed, while a
     * {@link MultipleWorkingDirectoriesCapability.primaryReplacement | replaceable
     * primary} is changed only with `session/workingDirectoryReplaced`.
     *
     * A client MUST NOT supply more than one entry unless the agent advertises
     * {@link AgentCapabilities.multipleWorkingDirectories}; a server without that
     * capability treats only the first entry as the session's working directory
     * and ignores the rest. Dispatch working-directory actions to change the set
     * after the session has started.
     *
     */
    workingDirectories?: URI[];
    /**
     * Agent-specific configuration values collected via `resolveSessionConfig`.
     * Keys and values correspond to the schema returned by the server.
     */
    config?: Record<string, unknown>;
    /**
     * Eagerly claim an active client role for the new session.
     *
     * When provided, the server initializes the session with this client as an
     * active client, equivalent to dispatching a `session/activeClientSet`
     * action immediately after creation. The `clientId` MUST match the
     * `clientId` the creating client supplied in `initialize`.
     */
    activeClient?: SessionActiveClient;
    /**
     * Opt-in progress token. When set, the client is offering to receive
     * `progress` notifications (see `ProgressParams`) for any long-running work
     * the server does to bring this session up — most notably the lazy,
     * first-use download of the provider's native SDK. The server echoes this
     * exact token on every `progress` frame so the client can correlate it to
     * this `createSession` call (and the UI awaiting it).
     *
     * The token MUST be unique across the client's active requests. The server
     * MAY ignore it (e.g. when nothing long-running is needed), in which case no
     * `progress` notifications are emitted.
     */
    progressToken?: string;
}
/**
 * Disposes a session and cleans up server-side resources.
 *
 * The server broadcasts a `root/sessionRemoved` notification to all clients.
 *
 * @category Commands
 * @method disposeSession
 * @direction Client → Server
 * @messageType Request
 * @version 1
 */
export interface DisposeSessionParams extends BaseParams {
}
/**
 * Requests that the host load older historical turns into a chat state.
 *
 * The command result does not carry turns. Instead, before responding, the host
 * MUST dispatch `chat/turnsLoaded` to insert any loaded turns into the chat
 * channel's `turns` state, ahead of the already-loaded window, and update or
 * clear `turnsNextCursor`.
 *
 * Before applying any operation that references a turn outside the currently
 * loaded window, the host MUST eagerly load enough older turns into state for
 * that operation to reduce against valid state.
 *
 * @category Commands
 * @method fetchTurns
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Client → Server (load the next page indicated by ChatState.turnsNextCursor)
 * { "jsonrpc": "2.0", "id": 8, "method": "fetchTurns",
 *   "params": { "channel": "ahp-chat:/<uuid>", "cursor": "opaque-cursor" } }
 *
 * // Server updates chat state, then responds
 * { "jsonrpc": "2.0", "id": 8, "result": {} }
 * ```
 */
export interface FetchTurnsParams extends BaseParams {
    /** Chat URI */
    channel: URI;
    /**
     * Opaque cursor from `ChatState.turnsNextCursor`.
     *
     * The host MUST reject unrecognised cursors with `InvalidParams`. Omit only
     * when asking the host to opportunistically load its next older page for the
     * chat, if any.
     */
    cursor?: string;
}
/**
 * Result of the `fetchTurns` command.
 */
export interface FetchTurnsResult {
}
/**
 * The kind of completion items being requested.
 *
 * @category Commands
 * @nonexhaustive
 */
export declare const enum CompletionItemKind {
    /**
     * Completions for the text of a {@link Message} the user is composing.
     * Each returned item carries an attachment that gets associated with the
     * message when accepted.
     */
    UserMessage = "userMessage"
}
/**
 * Requests completion items for a partially-typed input (e.g. a user message
 * the user is currently composing). Used to power `@`-mention pickers,
 * file/symbol references, and similar inline-completion experiences.
 *
 * Servers SHOULD treat this command as best-effort and return promptly. The
 * client SHOULD debounce calls to avoid flooding the server with requests on
 * every keystroke.
 *
 * @category Commands
 * @method completions
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // User has typed "look at @foo" and the cursor is just after "@foo".
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 12, "method": "completions",
 *   "params": { "kind": "userMessage", "channel": "ahp-chat:/<uuid>",
 *               "text": "look at @foo", "offset": 12 } }
 *
 * // Server → Client
 * { "jsonrpc": "2.0", "id": 12, "result": {
 *   "items": [
 *     {
 *       "insertText": "@foo.ts",
 *       "rangeStart": 8,
 *       "rangeEnd": 12,
 *       "attachment": {
 *         "type": "resource",
 *         "label": "foo.ts",
 *         "displayKind": "document",
 *         "uri": "file:///workspace/foo.ts"
 *       }
 *     }
 *   ]
 * }}
 * ```
 */
export interface CompletionsParams extends BaseParams {
    /** What kind of completion is being requested. */
    kind: CompletionItemKind;
    /** The chat URI the completion is being requested for. */
    channel: URI;
    /**
     * The complete text of the input being completed (e.g. the full user
     * message text typed so far).
     */
    text: string;
    /**
     * The character offset within `text` at which the completion is requested,
     * measured in UTF-16 code units. MUST satisfy `0 <= offset <= text.length`.
     */
    offset: number;
}
/**
 * A single completion item returned by the `completions` command.
 *
 * When the user accepts an item, the client SHOULD:
 * 1. Replace the range `[rangeStart, rangeEnd)` in the input with `insertText`
 *    (or insert `insertText` at the cursor when the range is omitted).
 * 2. Associate the item's `attachment` with the resulting {@link Message}.
 *
 * @category Commands
 */
export interface CompletionItem {
    /**
     * The text inserted into the input when this item is accepted.
     */
    insertText: string;
    /**
     * If defined, the start of the range in the input's `text` that is replaced
     * by `insertText`. The range is the half-open interval
     * `[rangeStart, rangeEnd)` of character offsets, measured in UTF-16 code
     * units.
     *
     * When omitted, the client SHOULD insert `insertText` at the cursor.
     *
     * Note: this range refers to positions in the *current* input. The
     * attachment's own `rangeStart`/`rangeEnd` (when present) refer to
     * positions in the final {@link Message.text} after the item is
     * accepted.
     */
    rangeStart?: number;
    /**
     * The end of the range in the input's `text` that is replaced by
     * `insertText`. See {@link rangeStart}.
     */
    rangeEnd?: number;
    /**
     * The attachment associated with this completion item.
     */
    attachment: MessageAttachment;
}
/**
 * Result of the `completions` command.
 */
export interface CompletionsResult {
    /** The completion items, in the order the server suggests displaying them. */
    items: CompletionItem[];
}
//# sourceMappingURL=commands.d.ts.map