@tylerl0706/ahpx 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,3397 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * State Types — Source of truth for all AHP state type definitions.
+ *
+ * @module state
+ * @description Complete reference for all state types in the Agent Host Protocol.
+ */
+/** A URI string (e.g. `agenthost:/root` or `copilot:/<uuid>`). */
+type URI = string;
+/**
+ * A string that may optionally be rendered as Markdown.
+ *
+ * - A plain `string` is rendered as-is (no Markdown processing).
+ * - An object with `{ markdown: string }` is rendered with Markdown formatting.
+ */
+type StringOrMarkdown = string | {
+    markdown: string;
+};
+/**
+ * An optionally-sized icon that can be displayed in a user interface.
+ *
+ * @category Common Types
+ */
+interface Icon {
+    /**
+     * A standard URI pointing to an icon resource. May be an HTTP/HTTPS URL or a
+     * `data:` URI with Base64-encoded image data.
+     *
+     * Consumers SHOULD take steps to ensure URLs serving icons are from the
+     * same domain as the client/server or a trusted domain.
+     *
+     * Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain
+     * executable JavaScript.
+     */
+    src: URI;
+    /**
+     * Optional MIME type override if the source MIME type is missing or generic.
+     * For example: `"image/png"`, `"image/jpeg"`, or `"image/svg+xml"`.
+     */
+    contentType?: string;
+    /**
+     * Optional array of strings that specify sizes at which the icon can be used.
+     * Each string should be in WxH format (e.g., `"48x48"`, `"96x96"`) or `"any"` for scalable formats like SVG.
+     *
+     * If not provided, the client should assume that the icon can be used at any size.
+     */
+    sizes?: string[];
+    /**
+     * Optional specifier for the theme this icon is designed for. `"light"` indicates
+     * the icon is designed to be used with a light background, and `"dark"` indicates
+     * the icon is designed to be used with a dark background.
+     *
+     * If not provided, the client should assume the icon can be used with any theme.
+     */
+    theme?: 'light' | 'dark';
+}
+/**
+ * Describes a protected resource's authentication requirements using
+ * [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (OAuth 2.0
+ * Protected Resource Metadata) semantics.
+ *
+ * Field names use snake_case to match the RFC 9728 JSON format.
+ *
+ * @category Authentication
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728}
+ */
+interface IProtectedResourceMetadata {
+    /**
+     * REQUIRED. The protected resource's resource identifier, a URL using the
+     * `https` scheme with no fragment component (e.g. `"https://api.github.com"`).
+     */
+    resource: string;
+    /** OPTIONAL. Human-readable name of the protected resource. */
+    resource_name?: string;
+    /** OPTIONAL. JSON array of OAuth authorization server identifier URLs. */
+    authorization_servers?: string[];
+    /** OPTIONAL. URL of the protected resource's JWK Set document. */
+    jwks_uri?: string;
+    /** RECOMMENDED. JSON array of OAuth 2.0 scope values used in authorization requests. */
+    scopes_supported?: string[];
+    /** OPTIONAL. JSON array of Bearer Token presentation methods supported. */
+    bearer_methods_supported?: string[];
+    /** OPTIONAL. JSON array of JWS signing algorithms supported. */
+    resource_signing_alg_values_supported?: string[];
+    /** OPTIONAL. JSON array of JWE encryption algorithms (alg) supported. */
+    resource_encryption_alg_values_supported?: string[];
+    /** OPTIONAL. JSON array of JWE encryption algorithms (enc) supported. */
+    resource_encryption_enc_values_supported?: string[];
+    /** OPTIONAL. URL of human-readable documentation for the resource. */
+    resource_documentation?: string;
+    /** OPTIONAL. URL of the resource's data-usage policy. */
+    resource_policy_uri?: string;
+    /** OPTIONAL. URL of the resource's terms of service. */
+    resource_tos_uri?: string;
+    /**
+     * AHP extension. Whether authentication is required for this resource.
+     *
+     * - `true` (default) — the agent cannot be used without a valid token.
+     *   The server SHOULD return `AuthRequired` (`-32007`) if the client
+     *   attempts to use the agent without authenticating.
+     * - `false` — the agent works without authentication but MAY offer
+     *   enhanced capabilities when a token is provided.
+     *
+     * Clients SHOULD treat an absent field the same as `true`.
+     */
+    required?: boolean;
+}
+/**
+ * Policy configuration state for a model.
+ *
+ * @category Root State
+ */
+declare const enum PolicyState {
+    Enabled = "enabled",
+    Disabled = "disabled",
+    Unconfigured = "unconfigured"
+}
+/**
+ * Global state shared with every client subscribed to `agenthost:/root`.
+ *
+ * @category Root State
+ */
+interface IRootState {
+    /** Available agent backends and their models */
+    agents: IAgentInfo[];
+    /** Number of active (non-disposed) sessions on the server */
+    activeSessions?: number;
+}
+/**
+ * @category Root State
+ */
+interface IAgentInfo {
+    /** Agent provider ID (e.g. `'copilot'`) */
+    provider: string;
+    /** Human-readable name */
+    displayName: string;
+    /** Description string */
+    description: string;
+    /** Available models for this agent */
+    models: ISessionModelInfo[];
+    /**
+     * 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?: IProtectedResourceMetadata[];
+    /**
+     * Customizations (Open Plugins) associated with this agent.
+     *
+     * Each entry is a reference to an [Open Plugins](https://open-plugins.com/)
+     * plugin that the agent host can activate for sessions using this agent.
+     */
+    customizations?: ICustomizationRef[];
+}
+/**
+ * @category Root State
+ */
+interface ISessionModelInfo {
+    /** 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;
+}
+/**
+ * Discriminant for pending message kinds.
+ *
+ * @category Pending Message Types
+ */
+declare const enum PendingMessageKind {
+    /** Injected into the current turn at a convenient point */
+    Steering = "steering",
+    /** Sent automatically as a new turn after the current turn finishes */
+    Queued = "queued"
+}
+/**
+ * A message queued for future delivery to the agent.
+ *
+ * Steering messages are injected into the current turn mid-flight.
+ * Queued messages are automatically started as new turns after the
+ * current turn naturally finishes.
+ *
+ * @category Pending Message Types
+ */
+interface IPendingMessage {
+    /** Unique identifier for this pending message */
+    id: string;
+    /** The message content */
+    userMessage: IUserMessage;
+}
+/**
+ * Session initialization state.
+ *
+ * @category Session State
+ */
+declare const enum SessionLifecycle {
+    Creating = "creating",
+    Ready = "ready",
+    CreationFailed = "creationFailed"
+}
+/**
+ * Current session status.
+ *
+ * @category Session State
+ */
+declare const enum SessionStatus {
+    Idle = "idle",
+    InProgress = "in-progress",
+    Error = "error"
+}
+/**
+ * Full state for a single session, loaded when a client subscribes to the session's URI.
+ *
+ * @category Session State
+ */
+interface ISessionState {
+    /** Lightweight session metadata */
+    summary: ISessionSummary;
+    /** Session initialization state */
+    lifecycle: SessionLifecycle;
+    /** Error details if creation failed */
+    creationError?: IErrorInfo;
+    /** Tools provided by the server (agent host) for this session */
+    serverTools?: IToolDefinition[];
+    /** The client currently providing tools and interactive capabilities to this session */
+    activeClient?: ISessionActiveClient;
+    /** The working directory URI for this session */
+    workingDirectory?: URI;
+    /** Completed turns */
+    turns: ITurn[];
+    /** Currently in-progress turn */
+    activeTurn?: IActiveTurn;
+    /** Message to inject into the current turn at a convenient point */
+    steeringMessage?: IPendingMessage;
+    /** Messages to send automatically as new turns after the current turn finishes */
+    queuedMessages?: IPendingMessage[];
+    /**
+     * Server-provided customizations active in this session.
+     *
+     * Client-provided customizations are available on
+     * {@link ISessionActiveClient.customizations | activeClient.customizations}.
+     */
+    customizations?: ISessionCustomization[];
+}
+/**
+ * The client currently providing tools and interactive capabilities to a session.
+ *
+ * Only one client may be active per session at a time. The server SHOULD
+ * automatically unset the active client if that client disconnects.
+ *
+ * @category Session State
+ */
+interface ISessionActiveClient {
+    /** Client identifier (matches `clientId` from `initialize`) */
+    clientId: string;
+    /** Human-readable client name (e.g. `"VS Code"`) */
+    displayName?: string;
+    /** Tools this client provides to the session */
+    tools: IToolDefinition[];
+    /** Customizations this client contributes to the session */
+    customizations?: ICustomizationRef[];
+}
+/**
+ * @category Session State
+ */
+interface ISessionSummary {
+    /** Session URI */
+    resource: URI;
+    /** Agent provider ID */
+    provider: string;
+    /** Session title */
+    title: string;
+    /** Current session status */
+    status: SessionStatus;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last modification timestamp */
+    modifiedAt: number;
+    /** Currently selected model */
+    model?: string;
+    /** The working directory URI for this session */
+    workingDirectory?: URI;
+}
+/**
+ * How a turn ended.
+ *
+ * @category Turn Types
+ */
+declare const enum TurnState {
+    Complete = "complete",
+    Cancelled = "cancelled",
+    Error = "error"
+}
+/**
+ * Type of a message attachment.
+ *
+ * @category Turn Types
+ */
+declare const enum AttachmentType {
+    File = "file",
+    Directory = "directory",
+    Selection = "selection"
+}
+/**
+ * A completed request/response cycle.
+ *
+ * @category Turn Types
+ */
+interface ITurn {
+    /** Turn identifier */
+    id: string;
+    /** The user's input */
+    userMessage: IUserMessage;
+    /**
+     * All response content in stream order: text, tool calls, reasoning, and content refs.
+     *
+     * Consumers should derive display text by concatenating markdown parts,
+     * and find tool calls by filtering for `ToolCall` parts.
+     */
+    responseParts: IResponsePart[];
+    /** Token usage info */
+    usage: IUsageInfo | undefined;
+    /** How the turn ended */
+    state: TurnState;
+    /** Error details if state is `'error'` */
+    error?: IErrorInfo;
+}
+/**
+ * An in-progress turn — the assistant is actively streaming.
+ *
+ * @category Turn Types
+ */
+interface IActiveTurn {
+    /** Turn identifier */
+    id: string;
+    /** The user's input */
+    userMessage: IUserMessage;
+    /**
+     * All response content in stream order: text, tool calls, reasoning, and content refs.
+     *
+     * Tool call parts include `pendingPermissions` when permissions are awaiting user approval.
+     */
+    responseParts: IResponsePart[];
+    /** Token usage info */
+    usage: IUsageInfo | undefined;
+}
+/**
+ * @category Turn Types
+ */
+interface IUserMessage {
+    /** Message text */
+    text: string;
+    /** File/selection attachments */
+    attachments?: IMessageAttachment[];
+}
+/**
+ * @category Turn Types
+ */
+interface IMessageAttachment {
+    /** Attachment type */
+    type: AttachmentType;
+    /** File/directory path */
+    path: string;
+    /** Display name */
+    displayName?: string;
+}
+/**
+ * Discriminant for response part types.
+ *
+ * @category Response Parts
+ */
+declare const enum ResponsePartKind {
+    Markdown = "markdown",
+    ContentRef = "contentRef",
+    ToolCall = "toolCall",
+    Reasoning = "reasoning"
+}
+/**
+ * @category Response Parts
+ */
+interface IMarkdownResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.Markdown;
+    /** Part identifier, used by `session/delta` to target this part for content appends */
+    id: string;
+    /** Markdown content */
+    content: string;
+}
+/**
+ * A reference to large content stored outside the state tree.
+ */
+interface IContentRef {
+    /** Content URI */
+    uri: URI;
+    /** Approximate size in bytes */
+    sizeHint?: number;
+    /** Content MIME type */
+    contentType?: string;
+}
+/**
+ * A content part that's a reference to large content stored outside the state tree.
+ *
+ * @category Response Parts
+ */
+interface IResourceReponsePart extends IContentRef {
+    /** Discriminant */
+    kind: ResponsePartKind.ContentRef;
+}
+/**
+ * A tool call represented as a response part.
+ *
+ * Tool calls are part of the response stream, interleaved with text and
+ * reasoning. The `toolCall.toolCallId` serves as the part identifier for
+ * actions that target this part.
+ *
+ * @category Response Parts
+ */
+interface IToolCallResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.ToolCall;
+    /** Full tool call lifecycle state */
+    toolCall: IToolCallState;
+}
+/**
+ * Reasoning/thinking content from the model.
+ *
+ * @category Response Parts
+ */
+interface IReasoningResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.Reasoning;
+    /** Part identifier, used by `session/reasoning` to target this part for content appends */
+    id: string;
+    /** Accumulated reasoning text */
+    content: string;
+}
+/**
+ * @category Response Parts
+ */
+type IResponsePart = IMarkdownResponsePart | IResourceReponsePart | IToolCallResponsePart | IReasoningResponsePart;
+/**
+ * Status of a tool call in the lifecycle state machine.
+ *
+ * @category Tool Call Types
+ */
+declare const enum ToolCallStatus {
+    Streaming = "streaming",
+    PendingConfirmation = "pending-confirmation",
+    Running = "running",
+    PendingResultConfirmation = "pending-result-confirmation",
+    Completed = "completed",
+    Cancelled = "cancelled"
+}
+/**
+ * How a tool call was confirmed for execution.
+ *
+ * - `NotNeeded` — No confirmation required (auto-approved)
+ * - `UserAction` — User explicitly approved
+ * - `Setting` — Approved by a persistent user setting
+ *
+ * @category Tool Call Types
+ */
+declare const enum ToolCallConfirmationReason {
+    NotNeeded = "not-needed",
+    UserAction = "user-action",
+    Setting = "setting"
+}
+/**
+ * Why a tool call was cancelled.
+ *
+ * @category Tool Call Types
+ */
+declare const enum ToolCallCancellationReason {
+    Denied = "denied",
+    Skipped = "skipped",
+    ResultDenied = "result-denied"
+}
+/**
+ * Metadata common to all tool call states.
+ *
+ * @category Tool Call Types
+ * @remarks
+ * Fields like `toolName` carry agent-specific identifiers on the wire despite the
+ * agent-agnostic design principle. These exist for debugging and logging purposes.
+ * A future version may move these to a separate diagnostic channel or namespace them
+ * more clearly.
+ */
+interface IToolCallBase {
+    /** Unique tool call identifier */
+    toolCallId: string;
+    /** Internal tool name (for debugging/logging) */
+    toolName: string;
+    /** Human-readable tool name */
+    displayName: string;
+    /**
+     * If this tool is provided by a client, the `clientId` of the owning client.
+     * Absent for server-side tools.
+     *
+     * When set, the identified client is responsible for executing the tool and
+     * dispatching `session/toolCallComplete` with the result.
+     */
+    toolClientId?: string;
+    /**
+     * Additional provider-specific metadata for this tool call.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI.
+     * For example, a `ptyTerminal` key with `{ input: string; output: string }`
+     * indicates the tool operated on a terminal (both `input` and `output` may
+     * contain escape sequences).
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Properties available once tool call parameters are fully received.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallParameterFields {
+    /** Message describing what the tool will do */
+    invocationMessage: StringOrMarkdown;
+    /** Raw tool input */
+    toolInput?: string;
+}
+/**
+ * Tool execution result details, available after execution completes.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallResult {
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Past-tense description of what the tool did */
+    pastTenseMessage: StringOrMarkdown;
+    /**
+     * Unstructured result content blocks.
+     *
+     * This mirrors the `content` field of MCP `CallToolResult`.
+     */
+    content?: IToolResultContent[];
+    /**
+     * Optional structured result object.
+     *
+     * This mirrors the `structuredContent` field of MCP `CallToolResult`.
+     */
+    structuredContent?: Record<string, unknown>;
+    /** Error details if the tool failed */
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * LM is streaming the tool call parameters.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallStreamingState extends IToolCallBase {
+    status: ToolCallStatus.Streaming;
+    /** Partial parameters accumulated so far */
+    partialInput?: string;
+    /** Progress message shown while parameters are streaming */
+    invocationMessage?: StringOrMarkdown;
+}
+/**
+ * Parameters are complete, or a running tool requires re-confirmation
+ * (e.g. a mid-execution permission check).
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallPendingConfirmationState extends IToolCallBase, IToolCallParameterFields {
+    status: ToolCallStatus.PendingConfirmation;
+    /** Short title for the confirmation prompt (e.g. `"Run in terminal"`, `"Write file"`) */
+    confirmationTitle?: StringOrMarkdown;
+}
+/**
+ * Tool is actively executing.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallRunningState extends IToolCallBase, IToolCallParameterFields {
+    status: ToolCallStatus.Running;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+}
+/**
+ * Tool finished executing, waiting for client to approve the result.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallPendingResultConfirmationState extends IToolCallBase, IToolCallParameterFields, IToolCallResult {
+    status: ToolCallStatus.PendingResultConfirmation;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+}
+/**
+ * Tool completed successfully or with an error.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallCompletedState extends IToolCallBase, IToolCallParameterFields, IToolCallResult {
+    status: ToolCallStatus.Completed;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+}
+/**
+ * Tool call was cancelled before execution.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallCancelledState extends IToolCallBase, IToolCallParameterFields {
+    status: ToolCallStatus.Cancelled;
+    /** Why the tool was cancelled */
+    reason: ToolCallCancellationReason;
+    /** Optional message explaining the cancellation */
+    reasonMessage?: StringOrMarkdown;
+    /** What the user suggested doing instead */
+    userSuggestion?: IUserMessage;
+}
+/**
+ * Discriminated union of all tool call lifecycle states.
+ *
+ * See the [state model guide](/guide/state-model.html#tool-call-lifecycle)
+ * for the full state machine diagram.
+ *
+ * @category Tool Call Types
+ */
+type IToolCallState = IToolCallStreamingState | IToolCallPendingConfirmationState | IToolCallRunningState | IToolCallPendingResultConfirmationState | IToolCallCompletedState | IToolCallCancelledState;
+/**
+ * Describes a tool available in a session, provided by either the server or the active client.
+ *
+ * This type mirrors the MCP `Tool` type from the Model Context Protocol specification
+ * (2025-11-25 draft) and will continue to track it.
+ *
+ * @category Tool Definition Types
+ */
+interface IToolDefinition {
+    /** Unique tool identifier */
+    name: string;
+    /** Human-readable display name */
+    title?: string;
+    /** Description of what the tool does */
+    description?: string;
+    /**
+     * JSON Schema defining the expected input parameters.
+     *
+     * Optional because client-provided tools may not have formal schemas.
+     * Mirrors MCP `Tool.inputSchema`.
+     */
+    inputSchema?: {
+        type: 'object';
+        properties?: Record<string, object>;
+        required?: string[];
+    };
+    /**
+     * JSON Schema defining the structure of the tool's output.
+     *
+     * Mirrors MCP `Tool.outputSchema`.
+     */
+    outputSchema?: {
+        type: 'object';
+        properties?: Record<string, object>;
+        required?: string[];
+    };
+    /** Behavioral hints about the tool. All properties are advisory. */
+    annotations?: IToolAnnotations;
+    /**
+     * Additional provider-specific metadata.
+     *
+     * Mirrors the MCP `_meta` convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Behavioral hints about a tool. All properties are advisory and not
+ * guaranteed to faithfully describe tool behavior.
+ *
+ * Mirrors MCP `ToolAnnotations` from the Model Context Protocol specification.
+ *
+ * @category Tool Definition Types
+ */
+interface IToolAnnotations {
+    /** Alternate human-readable title */
+    title?: string;
+    /** Tool does not modify its environment (default: false) */
+    readOnlyHint?: boolean;
+    /** Tool may perform destructive updates (default: true) */
+    destructiveHint?: boolean;
+    /** Repeated calls with the same arguments have no additional effect (default: false) */
+    idempotentHint?: boolean;
+    /** Tool may interact with external entities (default: true) */
+    openWorldHint?: boolean;
+}
+/**
+ * Discriminant for tool result content types.
+ *
+ * @category Tool Result Content
+ */
+declare const enum ToolResultContentType {
+    Text = "text",
+    EmbeddedResource = "embeddedResource",
+    Resource = "resource",
+    FileEdit = "fileEdit"
+}
+/**
+ * Text content in a tool result.
+ *
+ * Mirrors MCP `TextContent`.
+ *
+ * @category Tool Result Content
+ */
+interface IToolResultTextContent {
+    type: ToolResultContentType.Text;
+    /** The text content */
+    text: string;
+}
+/**
+ * Base64-encoded binary content embedded in a tool result.
+ *
+ * Mirrors MCP `EmbeddedResource` for inline binary data.
+ *
+ * @category Tool Result Content
+ */
+interface IToolResultEmbeddedResourceContent {
+    type: ToolResultContentType.EmbeddedResource;
+    /** Base64-encoded data */
+    data: string;
+    /** Content type (e.g. `"image/png"`, `"application/pdf"`) */
+    contentType: string;
+}
+/**
+ * A reference to a resource stored outside the tool result.
+ *
+ * Wraps {@link IContentRef} for lazy-loading large results.
+ *
+ * @category Tool Result Content
+ */
+interface IToolResultResourceContent extends IContentRef {
+    type: ToolResultContentType.Resource;
+}
+/**
+ * Describes a file modification performed by a tool.
+ *
+ * Supports creates (only `after`), deletes (only `before`), renames/moves
+ * (different `uri` in `before` and `after`), and edits (same `uri`, different content).
+ *
+ * @category Tool Result Content
+ */
+interface IToolResultFileEditContent {
+    type: ToolResultContentType.FileEdit;
+    /** The file state before the edit. Absent for file creations or for in-place file edits. */
+    before?: {
+        /** URI of the file before the edit */
+        uri: URI;
+        /** Reference to the file content before the edit */
+        content: IContentRef;
+    };
+    /** The file state after the edit. Absent for file deletions. */
+    after?: {
+        /** URI of the file after the edit */
+        uri: URI;
+        /** Reference to the file content after the edit */
+        content: IContentRef;
+    };
+    /** Optional diff display metadata */
+    diff?: {
+        /** Number of items added (e.g., lines for text files, cells for notebooks) */
+        added?: number;
+        /** Number of items removed (e.g., lines for text files, cells for notebooks) */
+        removed?: number;
+    };
+}
+/**
+ * Content block in a tool result.
+ *
+ * Mirrors the content blocks in MCP `CallToolResult.content`, plus
+ * `IToolResultResourceContent` for lazy-loading large results and
+ * `IToolResultFileEditContent` for file edit diffs (AHP extensions).
+ *
+ * @category Tool Result Content
+ */
+type IToolResultContent = IToolResultTextContent | IToolResultEmbeddedResourceContent | IToolResultResourceContent | IToolResultFileEditContent;
+/**
+ * A reference to an [Open Plugins](https://open-plugins.com/) plugin.
+ *
+ * This is intentionally thin — AHP specifies plugin identity and metadata
+ * but not implementation details, which are defined by the Open Plugins spec.
+ *
+ * @category Customization Types
+ */
+interface ICustomizationRef {
+    /** Plugin URI (e.g. an HTTPS URL or marketplace identifier) */
+    uri: URI;
+    /** Human-readable name */
+    displayName: string;
+    /** Description of what the plugin provides */
+    description?: string;
+    /** Icons for the plugin */
+    icons?: Icon[];
+    /**
+     * Opaque version token for this customization.
+     *
+     * Clients SHOULD include a nonce with every customization they provide.
+     * Consumers can compare nonces to detect whether a customization has
+     * changed since it was last seen, avoiding redundant reloads or copies.
+     */
+    nonce?: string;
+}
+/**
+ * Loading status for a server-managed customization.
+ *
+ * @category Customization Types
+ */
+declare const enum CustomizationStatus {
+    /** Plugin is being loaded */
+    Loading = "loading",
+    /** Plugin is fully operational */
+    Loaded = "loaded",
+    /** Plugin partially loaded but has warnings */
+    Degraded = "degraded",
+    /** Plugin was unable to load */
+    Error = "error"
+}
+/**
+ * A customization active in a session.
+ *
+ * Entries without a `clientId` are server-provided; entries with a `clientId`
+ * originate from that client.
+ *
+ * @category Customization Types
+ */
+interface ISessionCustomization {
+    /** The plugin this customization refers to */
+    customization: ICustomizationRef;
+    /** Whether this customization is currently enabled */
+    enabled: boolean;
+    /** Server-reported loading status */
+    status?: CustomizationStatus;
+    /**
+     * Human-readable status detail (e.g. error message or degradation warning).
+     */
+    statusMessage?: string;
+}
+/**
+ * @category Common Types
+ */
+interface IUsageInfo {
+    /** Input tokens consumed */
+    inputTokens?: number;
+    /** Output tokens generated */
+    outputTokens?: number;
+    /** Model used */
+    model?: string;
+    /** Tokens read from cache */
+    cacheReadTokens?: number;
+}
+/**
+ * @category Common Types
+ */
+interface IErrorInfo {
+    /** Error type identifier */
+    errorType: string;
+    /** Human-readable error message */
+    message: string;
+    /** Stack trace */
+    stack?: string;
+}
+/**
+ * A point-in-time snapshot of a subscribed resource's state, returned by
+ * `initialize`, `reconnect`, and `subscribe`.
+ *
+ * @category Common Types
+ */
+interface ISnapshot {
+    /** The subscribed resource URI (e.g. `agenthost:/root` or `copilot:/<uuid>`) */
+    resource: URI;
+    /** The current state of the resource */
+    state: IRootState | ISessionState;
+    /** The `serverSeq` at which this snapshot was taken. Subsequent actions will have `serverSeq > fromSeq`. */
+    fromSeq: number;
+}
+
+/**
+ * Action Types — Source of truth for all AHP action type definitions.
+ *
+ * @module actions
+ * @description Complete reference for all action types in the Agent Host Protocol.
+ * Actions are the sole mutation mechanism for subscribable state.
+ */
+
+/**
+ * Discriminant values for all state actions.
+ *
+ * @category Actions
+ */
+declare const enum ActionType {
+    RootAgentsChanged = "root/agentsChanged",
+    RootActiveSessionsChanged = "root/activeSessionsChanged",
+    SessionReady = "session/ready",
+    SessionCreationFailed = "session/creationFailed",
+    SessionTurnStarted = "session/turnStarted",
+    SessionDelta = "session/delta",
+    SessionResponsePart = "session/responsePart",
+    SessionToolCallStart = "session/toolCallStart",
+    SessionToolCallDelta = "session/toolCallDelta",
+    SessionToolCallReady = "session/toolCallReady",
+    SessionToolCallConfirmed = "session/toolCallConfirmed",
+    SessionToolCallComplete = "session/toolCallComplete",
+    SessionToolCallResultConfirmed = "session/toolCallResultConfirmed",
+    SessionTurnComplete = "session/turnComplete",
+    SessionTurnCancelled = "session/turnCancelled",
+    SessionError = "session/error",
+    SessionTitleChanged = "session/titleChanged",
+    SessionUsage = "session/usage",
+    SessionReasoning = "session/reasoning",
+    SessionModelChanged = "session/modelChanged",
+    SessionServerToolsChanged = "session/serverToolsChanged",
+    SessionActiveClientChanged = "session/activeClientChanged",
+    SessionActiveClientToolsChanged = "session/activeClientToolsChanged",
+    SessionPendingMessageSet = "session/pendingMessageSet",
+    SessionPendingMessageRemoved = "session/pendingMessageRemoved",
+    SessionQueuedMessagesReordered = "session/queuedMessagesReordered",
+    SessionCustomizationsChanged = "session/customizationsChanged",
+    SessionCustomizationToggled = "session/customizationToggled",
+    SessionTruncated = "session/truncated"
+}
+/**
+ * Identifies the client that originally dispatched an action.
+ */
+interface IActionOrigin {
+    clientId: string;
+    clientSeq: number;
+}
+/**
+ * Every action is wrapped in an `ActionEnvelope`.
+ */
+interface IActionEnvelope {
+    readonly action: IStateAction;
+    readonly serverSeq: number;
+    readonly origin: IActionOrigin | undefined;
+    readonly rejectionReason?: string;
+}
+/**
+ * Base interface for all tool-call-scoped actions, carrying the common
+ * session, turn, and tool call identifiers.
+ *
+ * @category Session Actions
+ */
+interface IToolCallActionBase {
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+    /** Tool call identifier */
+    toolCallId: string;
+    /**
+     * Additional provider-specific metadata for this tool call.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI.
+     * For example, a `ptyTerminal` key with `{ input: string; output: string }`
+     * indicates the tool operated on a terminal (both `input` and `output` may
+     * contain escape sequences).
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Fired when available agent backends or their models change.
+ *
+ * @category Root Actions
+ * @version 1
+ */
+interface IRootAgentsChangedAction {
+    type: ActionType.RootAgentsChanged;
+    /** Updated agent list */
+    agents: IAgentInfo[];
+}
+/**
+ * Fired when the number of active sessions changes.
+ *
+ * @category Root Actions
+ * @version 1
+ */
+interface IRootActiveSessionsChangedAction {
+    type: ActionType.RootActiveSessionsChanged;
+    /** Current count of active sessions */
+    activeSessions: number;
+}
+/**
+ * Session backend initialized successfully.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionReadyAction {
+    type: ActionType.SessionReady;
+    /** Session URI */
+    session: URI;
+}
+/**
+ * Session backend failed to initialize.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionCreationFailedAction {
+    type: ActionType.SessionCreationFailed;
+    /** Session URI */
+    session: URI;
+    /** Error details */
+    error: IErrorInfo;
+}
+/**
+ * User sent a message; server starts agent processing.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionTurnStartedAction {
+    type: ActionType.SessionTurnStarted;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+    /** User's message */
+    userMessage: IUserMessage;
+    /** If this turn was auto-started from a queued message, the ID of that message */
+    queuedMessageId?: string;
+}
+/**
+ * Streaming text chunk from the assistant, appended to a specific response part.
+ *
+ * The server MUST first emit a `session/responsePart` to create the target
+ * part (markdown or reasoning), then use this action to append text to it.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionDeltaAction {
+    type: ActionType.SessionDelta;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+    /** Identifier of the response part to append to */
+    partId: string;
+    /** Text chunk */
+    content: string;
+}
+/**
+ * Structured content appended to the response.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionResponsePartAction {
+    type: ActionType.SessionResponsePart;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+    /** Response part (markdown or content ref) */
+    part: IResponsePart;
+}
+/**
+ * A tool call begins — parameters are streaming from the LM.
+ *
+ * For client-provided tools, the server sets `toolClientId` to identify the
+ * owning client. That client is responsible for executing the tool once it
+ * reaches the `running` state and dispatching `session/toolCallComplete`.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionToolCallStartAction extends IToolCallActionBase {
+    type: ActionType.SessionToolCallStart;
+    /** Internal tool name (for debugging/logging) */
+    toolName: string;
+    /** Human-readable tool name */
+    displayName: string;
+    /**
+     * If this tool is provided by a client, the `clientId` of the owning client.
+     * Absent for server-side tools.
+     */
+    toolClientId?: string;
+}
+/**
+ * Streaming partial parameters for a tool call.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionToolCallDeltaAction extends IToolCallActionBase {
+    type: ActionType.SessionToolCallDelta;
+    /** Partial parameter content to append */
+    content: string;
+    /** Updated progress message */
+    invocationMessage?: StringOrMarkdown;
+}
+/**
+ * Tool call parameters are complete, or a running tool requires re-confirmation.
+ *
+ * When dispatched for a `streaming` tool call, transitions to `pending-confirmation`
+ * or directly to `running` if `confirmed` is set.
+ *
+ * When dispatched for a `running` tool call (e.g. mid-execution permission needed),
+ * transitions back to `pending-confirmation`. The `invocationMessage` and `_meta`
+ * SHOULD be updated to describe the specific confirmation needed. Clients use the
+ * standard `session/toolCallConfirmed` flow to approve or deny.
+ *
+ * For client-provided tools, the server typically sets `confirmed` to
+ * `'not-needed'` so the tool transitions directly to `running`, where the
+ * owning client can begin execution immediately.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionToolCallReadyAction extends IToolCallActionBase {
+    type: ActionType.SessionToolCallReady;
+    /** Message describing what the tool will do or what confirmation is needed */
+    invocationMessage: StringOrMarkdown;
+    /** Raw tool input */
+    toolInput?: string;
+    /** Short title for the confirmation prompt (e.g. `"Run in terminal"`, `"Write file"`) */
+    confirmationTitle?: StringOrMarkdown;
+    /** If set, the tool was auto-confirmed and transitions directly to `running` */
+    confirmed?: ToolCallConfirmationReason;
+}
+/**
+ * Client approves a pending tool call. The tool transitions to `running`.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionToolCallApprovedAction extends IToolCallActionBase {
+    type: ActionType.SessionToolCallConfirmed;
+    /** The tool call was approved */
+    approved: true;
+    /** How the tool was confirmed */
+    confirmed: ToolCallConfirmationReason;
+}
+/**
+ * Client denies a pending tool call. The tool transitions to `cancelled`.
+ *
+ * For client-provided tools, the owning client MUST dispatch this if it does
+ * not recognize the tool or cannot execute it.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionToolCallDeniedAction extends IToolCallActionBase {
+    type: ActionType.SessionToolCallConfirmed;
+    /** The tool call was denied */
+    approved: false;
+    /** Why the tool was cancelled */
+    reason: ToolCallCancellationReason.Denied | ToolCallCancellationReason.Skipped;
+    /** What the user suggested doing instead */
+    userSuggestion?: IUserMessage;
+    /** Optional explanation for the denial */
+    reasonMessage?: StringOrMarkdown;
+}
+/**
+ * Client confirms or denies a pending tool call.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+type ISessionToolCallConfirmedAction = ISessionToolCallApprovedAction | ISessionToolCallDeniedAction;
+/**
+ * Tool execution finished. Transitions to `completed` or `pending-result-confirmation`
+ * if `requiresResultConfirmation` is `true`.
+ *
+ * For client-provided tools (where `toolClientId` is set on the tool call state),
+ * the owning client dispatches this action with the execution result. The server
+ * SHOULD reject this action if the dispatching client does not match `toolClientId`.
+ *
+ * Servers waiting on a client tool call MAY time out after a reasonable duration
+ * if the implementing client disconnects or becomes unresponsive, and dispatch
+ * this action with `result.success = false` and an appropriate error.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionToolCallCompleteAction extends IToolCallActionBase {
+    type: ActionType.SessionToolCallComplete;
+    /** Execution result */
+    result: IToolCallResult;
+    /** If true, the result requires client approval before finalizing */
+    requiresResultConfirmation?: boolean;
+}
+/**
+ * Client approves or denies a tool's result.
+ *
+ * If `approved` is `false`, the tool transitions to `cancelled` with reason `result-denied`.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionToolCallResultConfirmedAction extends IToolCallActionBase {
+    type: ActionType.SessionToolCallResultConfirmed;
+    /** Whether the result was approved */
+    approved: boolean;
+}
+/**
+ * Turn finished — the assistant is idle.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionTurnCompleteAction {
+    type: ActionType.SessionTurnComplete;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+}
+/**
+ * Turn was aborted; server stops processing.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionTurnCancelledAction {
+    type: ActionType.SessionTurnCancelled;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+}
+/**
+ * Error during turn processing.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionErrorAction {
+    type: ActionType.SessionError;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+    /** Error details */
+    error: IErrorInfo;
+}
+/**
+ * Session title updated. Fired by the server when the title is auto-generated
+ * from conversation, or dispatched by a client to rename a session.
+ *
+ * @category Session Actions
+ * @clientDispatchable
+ * @version 1
+ */
+interface ISessionTitleChangedAction {
+    type: ActionType.SessionTitleChanged;
+    /** Session URI */
+    session: URI;
+    /** New title */
+    title: string;
+}
+/**
+ * Token usage report for a turn.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionUsageAction {
+    type: ActionType.SessionUsage;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+    /** Token usage data */
+    usage: IUsageInfo;
+}
+/**
+ * Reasoning/thinking text from the model, appended to a specific reasoning response part.
+ *
+ * The server MUST first emit a `session/responsePart` to create the target
+ * reasoning part, then use this action to append text to it.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionReasoningAction {
+    type: ActionType.SessionReasoning;
+    /** Session URI */
+    session: URI;
+    /** Turn identifier */
+    turnId: string;
+    /** Identifier of the reasoning response part to append to */
+    partId: string;
+    /** Reasoning text chunk */
+    content: string;
+}
+/**
+ * Model changed for this session.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionModelChangedAction {
+    type: ActionType.SessionModelChanged;
+    /** Session URI */
+    session: URI;
+    /** New model ID */
+    model: string;
+}
+/**
+ * Server tools for this session have changed.
+ *
+ * Full-replacement semantics: the `tools` array replaces the previous `serverTools` entirely.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionServerToolsChangedAction {
+    type: ActionType.SessionServerToolsChanged;
+    /** Session URI */
+    session: URI;
+    /** Updated server tools list (full replacement) */
+    tools: IToolDefinition[];
+}
+/**
+ * The active client for this session has changed.
+ *
+ * A client dispatches this action with its own `ISessionActiveClient` to claim
+ * the active role, or with `null` to release it. The server SHOULD reject if
+ * another client is already active. The server SHOULD automatically dispatch
+ * this action with `activeClient: null` when the active client disconnects.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionActiveClientChangedAction {
+    type: ActionType.SessionActiveClientChanged;
+    /** Session URI */
+    session: URI;
+    /** The new active client, or `null` to unset */
+    activeClient: ISessionActiveClient | null;
+}
+/**
+ * The active client's tool list has changed.
+ *
+ * Full-replacement semantics: the `tools` array replaces the active client's
+ * previous tools entirely. The server SHOULD reject if the dispatching client
+ * is not the current active client.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionActiveClientToolsChangedAction {
+    type: ActionType.SessionActiveClientToolsChanged;
+    /** Session URI */
+    session: URI;
+    /** Updated client tools list (full replacement) */
+    tools: IToolDefinition[];
+}
+/**
+ * The session's customizations have changed.
+ *
+ * Full-replacement semantics: the `customizations` array replaces the
+ * previous `customizations` entirely.
+ *
+ * @category Session Actions
+ * @version 1
+ */
+interface ISessionCustomizationsChangedAction {
+    type: ActionType.SessionCustomizationsChanged;
+    /** Session URI */
+    session: URI;
+    /** Updated customization list (full replacement) */
+    customizations: ISessionCustomization[];
+}
+/**
+ * A client toggled a customization on or off.
+ *
+ * The server locates the customization by `uri` in the session's
+ * customization list and sets its `enabled` flag.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionCustomizationToggledAction {
+    type: ActionType.SessionCustomizationToggled;
+    /** Session URI */
+    session: URI;
+    /** The URI of the customization to toggle */
+    uri: URI;
+    /** Whether to enable or disable the customization */
+    enabled: boolean;
+}
+/**
+ * Truncates a session's history. If `turnId` is provided, all turns after that
+ * turn are removed and the specified turn is kept. If `turnId` is omitted, all
+ * turns are removed.
+ *
+ * If there is an active turn it is silently dropped and the session status
+ * returns to `idle`.
+ *
+ * Common use-case: truncate old data then dispatch a new
+ * `session/turnStarted` with an edited message.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionTruncatedAction {
+    type: ActionType.SessionTruncated;
+    /** Session URI */
+    session: URI;
+    /** Keep turns up to and including this turn. Omit to clear all turns. */
+    turnId?: string;
+}
+/**
+ * A pending message was set (upsert semantics: creates or replaces).
+ *
+ * For steering messages, this always replaces the single steering message.
+ * For queued messages, if a message with the given `id` already exists it is
+ * updated in place; otherwise it is appended to the queue. If the session is
+ * idle when a queued message is set, the server SHOULD immediately consume it
+ * and start a new turn.
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionPendingMessageSetAction {
+    type: ActionType.SessionPendingMessageSet;
+    /** Session URI */
+    session: URI;
+    /** Whether this is a steering or queued message */
+    kind: PendingMessageKind;
+    /** Unique identifier for this pending message */
+    id: string;
+    /** The message content */
+    userMessage: IUserMessage;
+}
+/**
+ * A pending message was removed (steering or queued).
+ *
+ * Dispatched by clients to cancel a pending message, or by the server when
+ * it consumes a message (e.g. starting a turn from a queued message or
+ * injecting a steering message into the current turn).
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionPendingMessageRemovedAction {
+    type: ActionType.SessionPendingMessageRemoved;
+    /** Session URI */
+    session: URI;
+    /** Whether this is a steering or queued message */
+    kind: PendingMessageKind;
+    /** Identifier of the pending message to remove */
+    id: string;
+}
+/**
+ * Reorder the queued messages.
+ *
+ * The `order` array contains the IDs of queued messages in their new
+ * desired order. IDs not present in the current queue are ignored.
+ * Queued messages whose IDs are absent from `order` are appended at
+ * the end in their original relative order (so a client with a stale
+ * view of the queue never silently drops messages).
+ *
+ * @category Session Actions
+ * @version 1
+ * @clientDispatchable
+ */
+interface ISessionQueuedMessagesReorderedAction {
+    type: ActionType.SessionQueuedMessagesReordered;
+    /** Session URI */
+    session: URI;
+    /** Queued message IDs in the desired order */
+    order: string[];
+}
+/**
+ * Discriminated union of all state actions.
+ */
+type IStateAction = IRootAgentsChangedAction | IRootActiveSessionsChangedAction | ISessionReadyAction | ISessionCreationFailedAction | ISessionTurnStartedAction | ISessionDeltaAction | ISessionResponsePartAction | ISessionToolCallStartAction | ISessionToolCallDeltaAction | ISessionToolCallReadyAction | ISessionToolCallConfirmedAction | ISessionToolCallCompleteAction | ISessionToolCallResultConfirmedAction | ISessionTurnCompleteAction | ISessionTurnCancelledAction | ISessionErrorAction | ISessionTitleChangedAction | ISessionUsageAction | ISessionReasoningAction | ISessionModelChangedAction | ISessionServerToolsChangedAction | ISessionActiveClientChangedAction | ISessionActiveClientToolsChangedAction | ISessionPendingMessageSetAction | ISessionPendingMessageRemovedAction | ISessionQueuedMessagesReorderedAction | ISessionCustomizationsChangedAction | ISessionCustomizationToggledAction | ISessionTruncatedAction;
+
+/**
+ * Command Types — Source of truth for all AHP command (JSON-RPC request) definitions.
+ *
+ * @module commands
+ * @description Commands are JSON-RPC requests from the client to the server.
+ * They return a result or a JSON-RPC error.
+ */
+
+/**
+ * Establishes a new connection and negotiates the protocol version.
+ * This MUST be the first message sent by the client.
+ *
+ * @category Commands
+ * @method initialize
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/lifecycle | Lifecycle} for the full handshake flow.
+ */
+interface IInitializeParams {
+    /** Protocol version the client speaks */
+    protocolVersion: number;
+    /** Unique client identifier */
+    clientId: string;
+    /** URIs to subscribe to during handshake */
+    initialSubscriptions?: URI[];
+}
+/**
+ * Result of the `initialize` command.
+ *
+ * If the server does not support the client's protocol version, it MUST return
+ * error code `-32005` (`UnsupportedProtocolVersion`).
+ */
+interface IInitializeResult {
+    /** Protocol version the server speaks */
+    protocolVersion: number;
+    /** Current server sequence number */
+    serverSeq: number;
+    /** Snapshots for each `initialSubscriptions` URI */
+    snapshots: ISnapshot[];
+    /** Suggested default directory for remote filesystem browsing */
+    defaultDirectory?: URI;
+}
+/**
+ * Discriminant for reconnect result types.
+ *
+ * @category Commands
+ */
+declare const enum ReconnectResultType {
+    Replay = "replay",
+    Snapshot = "snapshot"
+}
+/**
+ * Re-establishes a dropped connection. The server replays missed actions or
+ * provides fresh snapshots.
+ *
+ * @category Commands
+ * @method reconnect
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/lifecycle | Lifecycle} for details.
+ */
+interface IReconnectParams {
+    /** Client identifier from the original connection */
+    clientId: string;
+    /** Last `serverSeq` the client received */
+    lastSeenServerSeq: number;
+    /** URIs the client was subscribed to */
+    subscriptions: URI[];
+}
+/**
+ * Reconnect result when the server can replay from the requested sequence.
+ *
+ * The server MUST include all replayed data in the response.
+ */
+interface IReconnectReplayResult {
+    /** Discriminant */
+    type: ReconnectResultType.Replay;
+    /** Missed action envelopes since `lastSeenServerSeq` */
+    actions: IActionEnvelope[];
+}
+/**
+ * Reconnect result when the gap exceeds the replay buffer.
+ */
+interface IReconnectSnapshotResult {
+    /** Discriminant */
+    type: ReconnectResultType.Snapshot;
+    /** Fresh snapshots for each subscription */
+    snapshots: ISnapshot[];
+}
+/** Result of the `reconnect` command. */
+type IReconnectResult = IReconnectReplayResult | IReconnectSnapshotResult;
+/**
+ * Subscribe to a URI-identified state resource.
+ *
+ * @category Commands
+ * @method subscribe
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/subscriptions | Subscriptions}
+ */
+interface ISubscribeParams {
+    /** URI to subscribe to */
+    resource: URI;
+}
+/**
+ * Result of the `subscribe` command.
+ */
+interface ISubscribeResult {
+    /** Snapshot of the subscribed resource */
+    snapshot: ISnapshot;
+}
+/**
+ * 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 `notify/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": { "session": "copilot:/<uuid>", "provider": "copilot", "model": "gpt-4o" } }
+ *
+ * // 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" } }
+ * ```
+ */
+/**
+ * Identifies a source session and turn to fork from.
+ *
+ * When provided in `createSession`, the server populates the new session with
+ * content from the source session up to and including the response of the
+ * specified turn.
+ */
+interface ISessionForkSource {
+    /** URI of the existing session to fork from */
+    session: URI;
+    /** Turn ID in the source session; content up to and including this turn's response is copied */
+    turnId: string;
+}
+interface ICreateSessionParams {
+    /** Session URI (client-chosen, e.g. `copilot:/<uuid>`) */
+    session: URI;
+    /** Agent provider ID */
+    provider?: string;
+    /** Model ID to use */
+    model?: string;
+    /** Working directory for the session */
+    workingDirectory?: URI;
+    /**
+     * Fork from an existing session. The new session is populated with content
+     * from the source session up to and including the specified turn's response.
+     */
+    fork?: ISessionForkSource;
+}
+/**
+ * Disposes a session and cleans up server-side resources.
+ *
+ * The server broadcasts a `notify/sessionRemoved` notification to all clients.
+ *
+ * @category Commands
+ * @method disposeSession
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+interface IDisposeSessionParams {
+    /** Session URI to dispose */
+    session: URI;
+}
+/**
+ * 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
+ * `notify/sessionAdded` and `notify/sessionRemoved` notifications.
+ *
+ * @category Commands
+ * @method listSessions
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+interface IListSessionsParams {
+    /** Optional filter criteria */
+    filter?: object;
+}
+/** Result of the `listSessions` command. */
+interface IListSessionsResult {
+    /** The list of session summaries. */
+    items: ISessionSummary[];
+}
+/**
+ * Encoding of fetched content data.
+ *
+ * @category Commands
+ */
+declare const enum ContentEncoding {
+    Base64 = "base64",
+    Utf8 = "utf-8"
+}
+/**
+ * Reads the content of a resource by URI.
+ *
+ * Content references keep the state tree small by storing large data (images,
+ * long tool outputs) by reference rather than inline.
+ *
+ * Binary content (images, etc.) MUST use `base64` encoding. Text content MAY
+ * use `utf-8` encoding.
+ *
+ * @category Commands
+ * @method resourceRead
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the URI does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to read the URI.
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 10, "method": "resourceRead",
+ *   "params": { "uri": "copilot:/<uuid>/content/img-1" } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 10, "result": {
+ *   "data": "iVBORw0KGgo...",
+ *   "encoding": "base64",
+ *   "contentType": "image/png"
+ * }}
+ * ```
+ */
+interface IResourceReadParams {
+    /** Content URI from a `ContentRef` */
+    uri: string;
+    /** Preferred encoding for the returned data (default: server-chosen) */
+    encoding?: ContentEncoding;
+}
+/**
+ * Result of the `resourceRead` command.
+ *
+ * The server SHOULD honor the `encoding` requested in the params. If the
+ * server cannot provide the requested encoding, it MUST fall back to either
+ * `base64` or `utf-8`.
+ */
+interface IResourceReadResult {
+    /** Content encoded as a string */
+    data: string;
+    /** How `data` is encoded */
+    encoding: ContentEncoding;
+    /** Content type (e.g. `"image/png"`, `"text/plain"`) */
+    contentType?: string;
+}
+/**
+ * Writes content to a file on the server's filesystem.
+ *
+ * Binary content (images, etc.) MUST use `base64` encoding. Text content MAY
+ * use `utf-8` encoding.
+ *
+ * If the file does not exist, it is created. If the file already exists, it is
+ * overwritten unless `createOnly` is set.
+ *
+ * @category Commands
+ * @method resourceWrite
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the parent directory does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to write to the path.
+ * @throws `AlreadyExists` (`-32010`) if `createOnly` is set and the file already exists.
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 11, "method": "resourceWrite",
+ *   "params": { "uri": "file:///workspace/hello.txt", "data": "SGVsbG8=",
+ *              "encoding": "base64", "contentType": "text/plain" } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 11, "result": {} }
+ * ```
+ */
+interface IResourceWriteParams {
+    /** Target file URI on the server filesystem */
+    uri: URI;
+    /** Content encoded as a string */
+    data: string;
+    /** How `data` is encoded */
+    encoding: ContentEncoding;
+    /** Content type (e.g. `"text/plain"`, `"image/png"`) */
+    contentType?: string;
+    /**
+     * If `true`, the server MUST fail if the file already exists instead of
+     * overwriting it. Useful for safe creation of new files.
+     */
+    createOnly?: boolean;
+}
+/**
+ * Result of the `resourceWrite` command.
+ *
+ * An empty object on success.
+ */
+interface IResourceWriteResult {
+}
+/**
+ * Lists directory entries at a file URI on the server's filesystem.
+ *
+ * This is intended for remote folder pickers and similar UI that needs to let
+ * users navigate the server's local filesystem.
+ *
+ * The server MUST return success only if the target exists and is a directory.
+ * If the target does not exist, is not a directory, or cannot be accessed, the
+ * server MUST return a JSON-RPC error.
+ *
+ * @category Commands
+ * @method resourceList
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the directory does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to browse the directory.
+ */
+interface IResourceListParams {
+    /** Directory URI on the server filesystem */
+    uri: URI;
+}
+/**
+ * Directory entry returned by `resourceList`.
+ */
+interface IDirectoryEntry {
+    /** Base name of the entry */
+    name: string;
+    /** Whether the entry is a file or directory */
+    type: 'file' | 'directory';
+}
+/**
+ * Result of the `resourceList` command.
+ */
+interface IResourceListResult {
+    /** Entries directly contained in the requested directory */
+    entries: IDirectoryEntry[];
+}
+/**
+ * Fetches historical turns for a session. Used for lazy loading of conversation
+ * history.
+ *
+ * @category Commands
+ * @method fetchTurns
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @example
+ * ```jsonc
+ * // Client → Server (fetch the 20 most recent turns)
+ * { "jsonrpc": "2.0", "id": 8, "method": "fetchTurns",
+ *   "params": { "session": "copilot:/<uuid>", "limit": 20 } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 8, "result": {
+ *   "turns": [ { "id": "t1", ... }, { "id": "t2", ... } ],
+ *   "hasMore": true
+ * }}
+ *
+ * // Client → Server (fetch 20 turns before t1)
+ * { "jsonrpc": "2.0", "id": 9, "method": "fetchTurns",
+ *   "params": { "session": "copilot:/<uuid>", "before": "t1", "limit": 20 } }
+ * ```
+ */
+interface IFetchTurnsParams {
+    /** Session URI */
+    session: URI;
+    /** Turn ID to fetch before (exclusive). Omit to fetch from the most recent turn. */
+    before?: string;
+    /** Maximum number of turns to return. Server MAY impose its own upper bound. */
+    limit?: number;
+}
+/**
+ * Result of the `fetchTurns` command.
+ */
+interface IFetchTurnsResult {
+    /** The requested turns, ordered oldest-first */
+    turns: ITurn[];
+    /** Whether more turns exist before the returned range */
+    hasMore: boolean;
+}
+/**
+ * Copies a resource from one URI to another on the server's filesystem.
+ *
+ * If the destination already exists, it is overwritten unless `failIfExists`
+ * is set.
+ *
+ * @category Commands
+ * @method resourceCopy
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the source does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to read the source or write to the destination.
+ * @throws `AlreadyExists` (`-32010`) if `failIfExists` is set and the destination already exists.
+ */
+interface IResourceCopyParams {
+    /** Source URI to copy from */
+    source: URI;
+    /** Destination URI to copy to */
+    destination: URI;
+    /**
+     * If `true`, the server MUST fail if the destination already exists instead
+     * of overwriting it.
+     */
+    failIfExists?: boolean;
+}
+/**
+ * Result of the `resourceCopy` command.
+ *
+ * An empty object on success.
+ */
+interface IResourceCopyResult {
+}
+/**
+ * Deletes a resource at a URI on the server's filesystem.
+ *
+ * @category Commands
+ * @method resourceDelete
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the resource does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to delete the resource.
+ */
+interface IResourceDeleteParams {
+    /** URI of the resource to delete */
+    uri: URI;
+    /**
+     * If `true` and the target is a directory, delete it and all its contents
+     * recursively. If `false` (default), deleting a non-empty directory MUST fail.
+     */
+    recursive?: boolean;
+}
+/**
+ * Result of the `resourceDelete` command.
+ *
+ * An empty object on success.
+ */
+interface IResourceDeleteResult {
+}
+/**
+ * Moves (renames) a resource from one URI to another on the server's filesystem.
+ *
+ * If the destination already exists, it is overwritten unless `failIfExists`
+ * is set.
+ *
+ * @category Commands
+ * @method resourceMove
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the source does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to move the resource.
+ * @throws `AlreadyExists` (`-32010`) if `failIfExists` is set and the destination already exists.
+ */
+interface IResourceMoveParams {
+    /** Source URI to move from */
+    source: URI;
+    /** Destination URI to move to */
+    destination: URI;
+    /**
+     * If `true`, the server MUST fail if the destination already exists instead
+     * of overwriting it.
+     */
+    failIfExists?: boolean;
+}
+/**
+ * Result of the `resourceMove` command.
+ *
+ * An empty object on success.
+ */
+interface IResourceMoveResult {
+}
+/**
+ * Pushes a Bearer token for a protected resource. The `resource` field MUST
+ * match an `IProtectedResourceMetadata.resource` value declared by an agent
+ * in `IAgentInfo.protectedResources`.
+ *
+ * Tokens are delivered using [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
+ * (Bearer Token Usage) semantics. The client obtains the token from the
+ * authorization server(s) listed in the resource's metadata and pushes it
+ * to the server via this command.
+ *
+ * @category Commands
+ * @method authenticate
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/authentication | Authentication}
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 3, "method": "authenticate",
+ *   "params": { "resource": "https://api.github.com", "token": "gho_xxxx" } }
+ *
+ * // Server → Client (success)
+ * { "jsonrpc": "2.0", "id": 3, "result": {} }
+ *
+ * // Server → Client (failure — invalid token)
+ * { "jsonrpc": "2.0", "id": 3, "error": { "code": -32007, "message": "Invalid token" } }
+ * ```
+ */
+interface IAuthenticateParams {
+    /**
+     * The protected resource identifier. MUST match a `resource` value from
+     * `IProtectedResourceMetadata` declared in `IAgentInfo.protectedResources`.
+     */
+    resource: string;
+    /** Bearer token obtained from the resource's authorization server */
+    token: string;
+}
+/**
+ * Result of the `authenticate` command.
+ *
+ * An empty object on success. If the token is invalid or the resource is
+ * unrecognized, the server MUST return a JSON-RPC error (e.g. `AuthRequired`
+ * `-32007` or `InvalidParams` `-32602`).
+ */
+interface IAuthenticateResult {
+}
+
+/**
+ * Notification Types — Source of truth for all AHP notification definitions.
+ *
+ * @module notifications
+ * @description Notifications are ephemeral broadcasts that are **not** part of the
+ * state tree. They are not processed by reducers and are not replayed on reconnection.
+ */
+
+/**
+ * Reason why authentication is required.
+ *
+ * @category Protocol Notifications
+ */
+declare const enum AuthRequiredReason {
+    /** The client has not yet authenticated for the resource */
+    Required = "required",
+    /** A previously valid token has expired or been revoked */
+    Expired = "expired"
+}
+/**
+ * Discriminant values for all protocol notifications.
+ *
+ * @category Protocol Notifications
+ */
+declare const enum NotificationType {
+    SessionAdded = "notify/sessionAdded",
+    SessionRemoved = "notify/sessionRemoved",
+    AuthRequired = "notify/authRequired"
+}
+/**
+ * Broadcast to all connected clients when a new session is created.
+ *
+ * @category Protocol Notifications
+ * @version 1
+ * @example
+ * ```json
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "notification",
+ *   "params": {
+ *     "notification": {
+ *       "type": "notify/sessionAdded",
+ *       "summary": {
+ *         "resource": "copilot:/<uuid>",
+ *         "provider": "copilot",
+ *         "title": "New Session",
+ *         "status": "idle",
+ *         "createdAt": 1710000000000,
+ *         "modifiedAt": 1710000000000
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface ISessionAddedNotification {
+    type: NotificationType.SessionAdded;
+    /** Summary of the new session */
+    summary: ISessionSummary;
+}
+/**
+ * Broadcast to all connected clients when a session is disposed.
+ *
+ * @category Protocol Notifications
+ * @version 1
+ * @example
+ * ```json
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "notification",
+ *   "params": {
+ *     "notification": {
+ *       "type": "notify/sessionRemoved",
+ *       "session": "copilot:/<uuid>"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface ISessionRemovedNotification {
+    type: NotificationType.SessionRemoved;
+    /** URI of the removed session */
+    session: URI;
+}
+/**
+ * Sent by the server when a protected resource requires (re-)authentication.
+ *
+ * This notification is sent when a previously valid token expires or is
+ * revoked, or when the server discovers a new authentication requirement.
+ * Clients should obtain a fresh token and push it via the `authenticate`
+ * command.
+ *
+ * @category Protocol Notifications
+ * @version 1
+ * @see {@link /specification/authentication | Authentication}
+ * @example
+ * ```json
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "notification",
+ *   "params": {
+ *     "notification": {
+ *       "type": "notify/authRequired",
+ *       "resource": "https://api.github.com",
+ *       "reason": "expired"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface IAuthRequiredNotification {
+    type: NotificationType.AuthRequired;
+    /** The protected resource identifier that requires authentication */
+    resource: string;
+    /** Why authentication is required */
+    reason?: AuthRequiredReason;
+}
+/**
+ * Discriminated union of all protocol notifications.
+ */
+type IProtocolNotification = ISessionAddedNotification | ISessionRemovedNotification | IAuthRequiredNotification;
+
+/**
+ * Message Types — Fully typed JSON-RPC message definitions for the AHP wire protocol.
+ *
+ * @module messages
+ * @description Typed JSON-RPC request, response, and notification types for all
+ * AHP methods. Narrowing on the `method` field gives fully typed `params` and
+ * result types.
+ */
+
+/**
+ * Registry mapping each command method name to its params and result types.
+ *
+ * @category Commands
+ */
+interface ICommandMap {
+    'initialize': {
+        params: IInitializeParams;
+        result: IInitializeResult;
+    };
+    'reconnect': {
+        params: IReconnectParams;
+        result: IReconnectResult;
+    };
+    'subscribe': {
+        params: ISubscribeParams;
+        result: ISubscribeResult;
+    };
+    'createSession': {
+        params: ICreateSessionParams;
+        result: null;
+    };
+    'disposeSession': {
+        params: IDisposeSessionParams;
+        result: null;
+    };
+    'listSessions': {
+        params: IListSessionsParams;
+        result: IListSessionsResult;
+    };
+    'resourceRead': {
+        params: IResourceReadParams;
+        result: IResourceReadResult;
+    };
+    'resourceWrite': {
+        params: IResourceWriteParams;
+        result: IResourceWriteResult;
+    };
+    'resourceList': {
+        params: IResourceListParams;
+        result: IResourceListResult;
+    };
+    'resourceCopy': {
+        params: IResourceCopyParams;
+        result: IResourceCopyResult;
+    };
+    'resourceDelete': {
+        params: IResourceDeleteParams;
+        result: IResourceDeleteResult;
+    };
+    'resourceMove': {
+        params: IResourceMoveParams;
+        result: IResourceMoveResult;
+    };
+    'fetchTurns': {
+        params: IFetchTurnsParams;
+        result: IFetchTurnsResult;
+    };
+    'authenticate': {
+        params: IAuthenticateParams;
+        result: IAuthenticateResult;
+    };
+}
+
+/**
+ * WebSocket transport layer for AHP protocol communication.
+ *
+ * Handles connection lifecycle, reconnection, and raw message framing.
+ */
+
+interface TransportOptions {
+    /** Connection timeout in ms (default: 10_000) */
+    connectTimeout?: number;
+    /** Headers to include in the WebSocket handshake */
+    headers?: Record<string, string>;
+}
+interface TransportEvents {
+    open: [];
+    close: [code: number, reason: string];
+    error: [error: Error];
+    message: [data: unknown];
+}
+/**
+ * Low-level WebSocket transport. Sends and receives JSON text frames.
+ */
+declare class Transport extends EventEmitter<TransportEvents> {
+    private ws;
+    private _connected;
+    get connected(): boolean;
+    /**
+     * Open a WebSocket connection to the given URL.
+     */
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    /**
+     * Send a JSON-serializable value over the WebSocket.
+     */
+    send(data: unknown): void;
+    /**
+     * Gracefully close the connection.
+     */
+    close(): void;
+    private attachListeners;
+}
+
+/**
+ * JSON-RPC 2.0 message routing layer for AHP protocol.
+ *
+ * Handles request/response correlation, notification dispatch,
+ * and incoming action/notification routing.
+ */
+
+/** Error thrown when a JSON-RPC request receives an error response. */
+declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+/** Error thrown when a request times out. */
+declare class RpcTimeoutError extends Error {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number);
+}
+interface ProtocolLayerOptions {
+    /** Default request timeout in ms (default: 30_000) */
+    requestTimeout?: number;
+}
+interface ProtocolLayerEvents {
+    action: [envelope: IActionEnvelope];
+    notification: [notification: IProtocolNotification];
+}
+/**
+ * JSON-RPC 2.0 protocol layer over a Transport.
+ *
+ * - Sends requests with auto-incrementing IDs and returns Promises
+ * - Sends notifications (fire-and-forget, no ID)
+ * - Routes incoming messages to pending request resolvers or event emitters
+ */
+declare class ProtocolLayer extends EventEmitter<ProtocolLayerEvents> {
+    private readonly transport;
+    private nextId;
+    private pending;
+    private readonly requestTimeout;
+    constructor(transport: Transport, options?: ProtocolLayerOptions);
+    /**
+     * Send a typed JSON-RPC request and await the response.
+     */
+    request<M extends keyof ICommandMap>(method: M, params: ICommandMap[M]["params"], timeoutMs?: number): Promise<ICommandMap[M]["result"]>;
+    /**
+     * Send a JSON-RPC notification (no response expected).
+     */
+    notify(method: string, params: unknown): void;
+    /**
+     * Cancel all pending requests (e.g. on disconnect).
+     */
+    cancelAll(reason: string): void;
+    private handleMessage;
+}
+
+/**
+ * SessionHandle — Convenience wrapper for a single session on an AhpClient.
+ *
+ * Filters events by session URI, provides a cleaner API for sending prompts,
+ * cancelling turns, and accessing session state. Library consumers work with
+ * SessionHandle instead of raw `client.dispatchAction()` calls.
+ */
+
+/** Options for sending a prompt via SessionHandle. */
+interface PromptOptions {
+    /** File or directory attachments to include with the message. */
+    attachments?: IMessageAttachment[];
+    /** Timeout in ms for the entire turn (default: none). */
+    timeout?: number;
+}
+/** Result of a completed turn. */
+interface TurnResult {
+    turnId: string;
+    responseText: string;
+    toolCalls: number;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        model?: string;
+    };
+    state: "complete" | "cancelled" | "error";
+    error?: string;
+}
+/** Events emitted by SessionHandle, scoped to a single session. */
+interface SessionHandleEvents {
+    /** Any action for this session. */
+    action: [envelope: IActionEnvelope];
+    /** A turn completed successfully. */
+    turnComplete: [turn: ITurn];
+    /** An error occurred on this session. */
+    error: [error: Error];
+    /** Session was disposed. */
+    disposed: [];
+}
+/**
+ * A handle to a single session on an AhpClient.
+ *
+ * Provides a session-scoped view: events are filtered to only this session,
+ * state accessors read from the client's state mirror, and action dispatch
+ * auto-injects the session URI.
+ */
+declare class SessionHandle extends EventEmitter<SessionHandleEvents> {
+    private readonly client;
+    readonly uri: URI;
+    readonly provider: string;
+    readonly model?: string;
+    private _disposed;
+    private _activeTurnId;
+    private readonly _onAction;
+    private readonly _onDisconnect;
+    constructor(client: AhpClient, uri: URI, provider: string, model?: string);
+    /** Current session state from the state mirror. */
+    get state(): ISessionState | undefined;
+    /** Whether the session is ready for prompts. */
+    get isReady(): boolean;
+    /** The currently active turn, if any. */
+    get activeTurn(): IActiveTurn | undefined;
+    /** Whether this handle has been disposed. */
+    get disposed(): boolean;
+    /**
+     * Wait for the session to reach the "ready" lifecycle state.
+     *
+     * Resolves immediately if already ready. Rejects on creation failure
+     * or timeout.
+     */
+    waitForReady(timeout?: number): Promise<void>;
+    /**
+     * Dispose this session handle and clean up server-side resources.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Send a prompt and wait for the turn to complete.
+     *
+     * Returns a `TurnResult` when the turn finishes (complete, error, or cancelled).
+     * Tool call confirmations and permissions are NOT handled automatically —
+     * library consumers should listen to `handle.on('action', ...)` and use
+     * `handle.dispatchAction()` for tool/permission responses.
+     */
+    sendPrompt(text: string, options?: PromptOptions): Promise<TurnResult>;
+    /**
+     * Cancel the currently active turn.
+     */
+    cancelTurn(): Promise<void>;
+    /**
+     * Dispatch a client action for this session.
+     *
+     * Automatically injects the session URI into the action. Use this for
+     * tool call confirmations, permission responses, model changes, etc.
+     */
+    dispatchAction(action: Record<string, unknown> & {
+        type: string;
+    }): void;
+    private ensureNotDisposed;
+}
+
+/**
+ * Local state mirror — applies incoming actions through the AHP reducers.
+ *
+ * Maintains a client-side copy of root state and session states,
+ * kept in sync by applying action envelopes from the server.
+ */
+
+/**
+ * Client-side state mirror that tracks root and session states
+ * by applying incoming action envelopes through the protocol reducers.
+ */
+declare class StateMirror {
+    private rootState;
+    private sessions;
+    private serverSeq;
+    /** Current root state (agents, active session count). */
+    get root(): IRootState;
+    /** Current server sequence number. */
+    get seq(): number;
+    /** Get a session state by URI. */
+    getSession(uri: URI): ISessionState | undefined;
+    /** All tracked session URIs. */
+    get sessionUris(): URI[];
+    /**
+     * Load a snapshot (from initialize, reconnect, or subscribe).
+     */
+    applySnapshot(snapshot: ISnapshot): void;
+    /**
+     * Apply an incoming action envelope from the server.
+     */
+    applyAction(envelope: IActionEnvelope): void;
+    /**
+     * Remove a session from tracking (e.g. after dispose or unsubscribe).
+     */
+    removeSession(uri: URI): void;
+}
+
+/**
+ * ActiveClientManager — Manages active client status for AHP sessions.
+ *
+ * AHP sessions have an "active client" concept — only one client at a time
+ * provides tools to the session. This manager handles claiming/releasing
+ * active status and registering tools.
+ */
+
+/**
+ * Manages active client status and tool registration for AHP sessions.
+ */
+declare class ActiveClientManager {
+    private readonly client;
+    private readonly clientId;
+    /** Sessions where this client is the active client. */
+    private readonly activeSessions;
+    constructor(client: AhpClient, clientId: string);
+    /**
+     * Claim active client status for a session.
+     * Dispatches `session/activeClientChanged` with this client's info.
+     */
+    claimActiveClient(sessionUri: URI, displayName?: string, tools?: IToolDefinition[]): Promise<void>;
+    /**
+     * Release active client status for a session.
+     * Dispatches `session/activeClientChanged` with `null`.
+     */
+    releaseActiveClient(sessionUri: URI): Promise<void>;
+    /**
+     * Check if this client is the active client for a session.
+     * Uses the local state mirror for the check.
+     */
+    isActiveClient(sessionUri: URI): boolean;
+    /**
+     * Register (or update) the tools this client provides to a session.
+     * Dispatches `session/activeClientToolsChanged`.
+     * Only valid when this client is the active client.
+     */
+    registerTools(sessionUri: URI, tools: IToolDefinition[]): Promise<void>;
+    /**
+     * Handle a tool call directed at this client.
+     * Dispatches `session/toolCallComplete` with the result.
+     */
+    completeToolCall(sessionUri: URI, turnId: string, toolCallId: string, result: {
+        success: boolean;
+        pastTenseMessage: string;
+        content?: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }): void;
+    /**
+     * Get the set of sessions where this client is active.
+     */
+    get sessions(): ReadonlySet<URI>;
+}
+
+/**
+ * ReconnectManager — Handles automatic reconnection with exponential backoff.
+ *
+ * When the WebSocket connection drops, attempts to reconnect using the
+ * AHP `reconnect` command. Supports both `replay` (apply missed actions)
+ * and `snapshot` (reset state) recovery modes.
+ */
+
+interface ReconnectOptions {
+    /** Maximum number of reconnect attempts (default: 5) */
+    maxRetries?: number;
+    /** Initial backoff in milliseconds (default: 1000) */
+    backoffMs?: number;
+    /** Maximum backoff in milliseconds (default: 30000) */
+    maxBackoffMs?: number;
+    /** Stream for status messages (default: process.stderr) */
+    statusOut?: {
+        write(data: string): void;
+    };
+}
+type ReconnectOutcome = "replay" | "snapshot" | "failed";
+/**
+ * Manages reconnection to an AHP server with exponential backoff.
+ */
+declare class ReconnectManager {
+    private readonly serverUrl;
+    private readonly clientId;
+    private readonly maxRetries;
+    private readonly backoffMs;
+    private readonly maxBackoffMs;
+    private readonly statusOut;
+    private aborted;
+    constructor(serverUrl: string, clientId: string, options?: ReconnectOptions);
+    /**
+     * Attempt to reconnect to the AHP server.
+     *
+     * @param client - The AhpClient to reconnect
+     * @param lastSeenServerSeq - Last server sequence number received
+     * @param subscriptions - URIs the client was subscribed to
+     * @returns The reconnect outcome (replay, snapshot, or failed)
+     */
+    reconnect(client: AhpClient, _lastSeenServerSeq: number, subscriptions: URI[]): Promise<ReconnectOutcome>;
+    /**
+     * Abort any in-progress reconnection attempt.
+     */
+    abort(): void;
+    /**
+     * Sleep for a given number of milliseconds. Can be aborted.
+     */
+    private sleep;
+}
+
+/**
+ * AhpClient — High-level AHP protocol client.
+ *
+ * Composes Transport + ProtocolLayer + StateMirror into a single
+ * interface for connecting to AHP servers, managing sessions, and
+ * dispatching actions.
+ */
+
+interface AhpClientOptions extends TransportOptions, ProtocolLayerOptions {
+    /** Unique client identifier (default: random UUID) */
+    clientId?: string;
+    /** URIs to subscribe to during initialization */
+    initialSubscriptions?: URI[];
+}
+interface AhpClientEvents {
+    action: [envelope: IActionEnvelope];
+    notification: [notification: IProtocolNotification];
+    connected: [result: IInitializeResult];
+    disconnected: [code: number, reason: string];
+    error: [error: Error];
+}
+/** Options for opening a session via `AhpClient.openSession()`. */
+interface OpenSessionOptions {
+    /** Agent provider (e.g. "copilot"). If omitted, uses the first available. */
+    provider?: string;
+    /** Model to use for the session. */
+    model?: string;
+    /** Working directory for the session. */
+    workingDirectory?: string;
+    /** Whether to wait for the session to be ready (default: true). */
+    waitForReady?: boolean;
+    /** Timeout in ms for waiting for ready state (default: 30000). */
+    readyTimeout?: number;
+}
+/**
+ * High-level AHP client.
+ *
+ * Usage:
+ * ```ts
+ * const client = new AhpClient();
+ * const result = await client.connect("ws://localhost:3000");
+ * console.log(result.snapshots[0].state);
+ * await client.disconnect();
+ * ```
+ */
+declare class AhpClient extends EventEmitter<AhpClientEvents> {
+    private readonly options;
+    private transport;
+    private protocol;
+    private readonly _state;
+    private readonly _sessions;
+    private _clientId;
+    private _clientSeq;
+    private _connected;
+    constructor(options?: AhpClientOptions);
+    /** Whether the client is currently connected. */
+    get connected(): boolean;
+    /** The local state mirror. */
+    get state(): StateMirror;
+    /** The client identifier. */
+    get clientId(): string;
+    /** All active session handles. */
+    get sessions(): ReadonlyMap<string, SessionHandle>;
+    /**
+     * Connect to an AHP server and perform the initialization handshake.
+     */
+    connect(url: string): Promise<IInitializeResult>;
+    /**
+     * Gracefully disconnect from the server.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Create a session and return a handle for interacting with it.
+     *
+     * Creates the session on the server, subscribes to its state, and
+     * (by default) waits for it to reach the "ready" lifecycle state.
+     */
+    openSession(options?: OpenSessionOptions): Promise<SessionHandle>;
+    /**
+     * Create a new session with the specified agent provider.
+     */
+    createSession(sessionUri: URI, provider?: string, model?: string, workingDirectory?: string): Promise<null>;
+    /**
+     * Dispose a session and clean up server-side resources.
+     */
+    disposeSession(sessionUri: URI): Promise<null>;
+    /**
+     * List all sessions on the server.
+     */
+    listSessions(): Promise<IListSessionsResult>;
+    /**
+     * Subscribe to a state resource URI.
+     */
+    subscribe(resourceUri: URI): Promise<ISubscribeResult>;
+    /**
+     * Unsubscribe from a state resource URI.
+     */
+    unsubscribe(resourceUri: URI): void;
+    /**
+     * Fetch historical turns for a session.
+     */
+    fetchTurns(sessionUri: URI, before?: string, limit?: number): Promise<IFetchTurnsResult>;
+    /**
+     * Read content by URI (files, tool outputs, etc.).
+     */
+    resourceRead(uri: string, encoding?: ContentEncoding): Promise<IResourceReadResult>;
+    /**
+     * Write content to a file on the server's filesystem.
+     */
+    resourceWrite(params: IResourceWriteParams): Promise<IResourceWriteResult>;
+    /**
+     * List directory entries on the server's filesystem.
+     */
+    resourceList(uri: URI): Promise<IResourceListResult>;
+    /**
+     * Copy a resource from one URI to another.
+     */
+    resourceCopy(params: IResourceCopyParams): Promise<IResourceCopyResult>;
+    /**
+     * Delete a resource at a URI.
+     */
+    resourceDelete(params: IResourceDeleteParams): Promise<IResourceDeleteResult>;
+    /**
+     * Move (rename) a resource from one URI to another.
+     */
+    resourceMove(params: IResourceMoveParams): Promise<IResourceMoveResult>;
+    /**
+     * Dispatch a client-originated action to the server.
+     */
+    dispatchAction(action: IStateAction): void;
+    /**
+     * Push an authentication token for a protected resource.
+     */
+    authenticate(resource: string, token: string): Promise<void>;
+    private ensureConnected;
+}
+
+/**
+ * ConnectionPool — Manages reusable AhpClient connections to multiple servers.
+ *
+ * For library consumers managing multiple servers, the pool ensures
+ * that only one WebSocket connection exists per server URL, and provides
+ * aggregate stats across all connections and sessions.
+ */
+
+/** Options for the ConnectionPool. */
+interface ConnectionPoolOptions {
+    /** Maximum concurrent connections per server URL (default: 1). */
+    maxConnectionsPerServer?: number;
+}
+/**
+ * Pool of AhpClient connections, keyed by server URL.
+ *
+ * Reuses existing connections to the same server URL. Each connection
+ * is an `AhpClient` that can host multiple concurrent sessions.
+ *
+ * @example
+ * ```ts
+ * const pool = new ConnectionPool();
+ * const client = await pool.getClient("ws://localhost:8082");
+ * const session = await client.openSession({ provider: "copilot" });
+ * // ... use session ...
+ * await pool.closeAll();
+ * ```
+ */
+declare class ConnectionPool {
+    private readonly _clients;
+    private readonly _maxPerServer;
+    constructor(options?: ConnectionPoolOptions);
+    /**
+     * Get or create a connected client for the given server URL.
+     *
+     * If a connected client already exists for this URL, it is returned.
+     * Otherwise a new client is created, connected, and cached.
+     */
+    getClient(url: string, options?: AhpClientOptions): Promise<AhpClient>;
+    /**
+     * Close all connections in the pool.
+     */
+    closeAll(): Promise<void>;
+    /** Number of active connections in the pool. */
+    get activeConnections(): number;
+    /** Total number of active sessions across all connections. */
+    get activeSessions(): number;
+    private normalizeUrl;
+}
+
+/**
+ * PromptRenderer — Streaming terminal renderer for AHP turn output.
+ *
+ * Renders deltas, reasoning blocks, tool calls, permissions, usage,
+ * and turn lifecycle events to stdout with color formatting via picocolors.
+ */
+
+/** Minimal info about a tool call ready for display. */
+interface ToolCallInfo {
+    toolCallId: string;
+    toolName: string;
+    displayName: string;
+    invocationMessage: StringOrMarkdown;
+    toolInput?: string;
+}
+
+/**
+ * OutputFormatter — Abstraction layer for CLI output formatting.
+ *
+ * Three modes:
+ *   - text:  Colored terminal output via PromptRenderer
+ *   - json:  NDJSON (one JSON object per line)
+ *   - quiet: Accumulates silently, prints only the final response
+ */
+
+/**
+ * Interface implemented by all output formatters.
+ *
+ * The TurnController calls these methods as actions arrive from the server.
+ * Each formatter decides how (or whether) to render them.
+ */
+interface OutputFormatter {
+    onDelta(text: string): void;
+    onReasoning(text: string): void;
+    onToolCallStart(id: string, name: string): void;
+    onToolCallDelta(id: string, paramsDelta: string): void;
+    onToolCallReady(id: string, call: ToolCallInfo): void;
+    onToolCallComplete(id: string, result: IToolCallResult): void;
+    onToolCallCancelled(id: string, reason: string): void;
+    onUsage(usage: IUsageInfo): void;
+    onTurnComplete(responseText: string): void;
+    onTurnError(error: IErrorInfo): void;
+    onTurnCancelled(): void;
+    onTitleChanged(title: string): void;
+}
+
+/**
+ * JSON Formatter — NDJSON output (one JSON object per line).
+ *
+ * Each event has a stable envelope:
+ * ```json
+ * { "type": "delta", "timestamp": "<ISO>", "data": { ... } }
+ * ```
+ *
+ * Raw protocol data goes in `data` — no renaming or reshaping.
+ *
+ * When `strict` mode is enabled, non-JSON stderr output is suppressed.
+ */
+
+type JsonEventType = "delta" | "reasoning" | "tool_call_start" | "tool_call_delta" | "tool_call_ready" | "tool_call_complete" | "tool_call_cancelled" | "usage" | "turn_complete" | "turn_error" | "turn_cancelled" | "title_changed";
+
+/**
+ * Event Forwarder — Pluggable event forwarding system.
+ *
+ * Defines the `AhpxEvent` shape and the `EventForwarder` interface.
+ * Implementations (WebhookForwarder, WebSocketForwarder) forward events
+ * to external consumers: dashboards, log aggregators, monitoring systems.
+ *
+ * Events match the JsonEnvelope shape from the NDJSON formatter, extended
+ * with `sessionUri` for multi-session disambiguation.
+ */
+
+/**
+ * An event emitted by ahpx, suitable for forwarding to external consumers.
+ *
+ * Intentionally compatible with `JsonEnvelope` from the NDJSON formatter,
+ * but with an additional `sessionUri` field for multi-session support.
+ */
+interface AhpxEvent {
+    /** Event type (e.g. "delta", "tool_call_complete", "turn_complete"). */
+    type: JsonEventType | (string & {});
+    /** ISO 8601 timestamp of when the event was generated. */
+    timestamp: string;
+    /** Optional metadata tags (e.g. jobId, project, environment). */
+    tags?: Record<string, string>;
+    /** Event payload — raw protocol data, no renaming or reshaping. */
+    data: Record<string, unknown>;
+    /** Session URI this event belongs to (for multi-session disambiguation). */
+    sessionUri?: string;
+}
+/**
+ * Interface for forwarding events to external consumers.
+ *
+ * Implementations handle transport, batching, retry, and filtering.
+ * The `forward()` method may buffer events internally — call `close()`
+ * to flush any remaining events and release resources.
+ */
+interface EventForwarder {
+    /** Forward an event to the external consumer. May buffer internally. */
+    forward(event: AhpxEvent): Promise<void>;
+    /** Flush buffered events and release resources. */
+    close(): Promise<void>;
+}
+
+/**
+ * Webhook Forwarder — POST events to an HTTP endpoint.
+ *
+ * Batches events to reduce HTTP requests, retries with exponential backoff
+ * on failure, supports event type filtering, and buffers events if the
+ * endpoint is temporarily down. Flushes remaining events on `close()`.
+ */
+
+interface WebhookForwarderOptions {
+    /** URL to POST events to. */
+    url: string;
+    /** Custom HTTP headers to include in requests. */
+    headers?: Record<string, string>;
+    /** Number of events to batch before sending (default: 10). */
+    batchSize?: number;
+    /** Max milliseconds to wait before flushing a partial batch (default: 1000). */
+    batchIntervalMs?: number;
+    /** Number of retry attempts on failure (default: 3). */
+    retries?: number;
+    /** Event types to forward. If empty/undefined, forwards all. */
+    filter?: string[];
+}
+declare class WebhookForwarder implements EventForwarder {
+    private readonly url;
+    private readonly headers;
+    private readonly batchSize;
+    private readonly batchIntervalMs;
+    private readonly retries;
+    private readonly filter;
+    private batch;
+    private flushTimer;
+    private closed;
+    private flushPromise;
+    constructor(options: WebhookForwarderOptions);
+    forward(event: AhpxEvent): Promise<void>;
+    close(): Promise<void>;
+    private startFlushTimer;
+    private clearFlushTimer;
+    private flush;
+    private sendWithRetry;
+    private send;
+}
+
+/**
+ * WebSocket Forwarder — Stream events over a WebSocket connection.
+ *
+ * Connects to a WebSocket endpoint and streams events in real-time.
+ * Auto-reconnects on disconnect, supports event type filtering,
+ * and handles backpressure by buffering when the WebSocket buffer is full.
+ */
+
+interface WebSocketForwarderOptions {
+    /** WebSocket URL to connect to (ws:// or wss://). */
+    url: string;
+    /** Custom headers for the WebSocket handshake. */
+    headers?: Record<string, string>;
+    /** Auto-reconnect on disconnect (default: true). */
+    reconnect?: boolean;
+    /** Event types to forward. If empty/undefined, forwards all. */
+    filter?: string[];
+}
+declare class WebSocketForwarder implements EventForwarder {
+    private readonly url;
+    private readonly headers;
+    private readonly reconnect;
+    private readonly filter;
+    private ws;
+    private buffer;
+    private closed;
+    private reconnecting;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private connectPromise;
+    constructor(options: WebSocketForwarderOptions);
+    forward(event: AhpxEvent): Promise<void>;
+    close(): Promise<void>;
+    private connect;
+    private scheduleReconnect;
+    private isConnected;
+    private sendOrBuffer;
+    private addToBuffer;
+    private drainBuffer;
+}
+
+/**
+ * Forwarding Formatter — Decorator that wraps an OutputFormatter and
+ * forwards events to one or more EventForwarder instances.
+ *
+ * Each OutputFormatter method is delegated to the inner formatter AND
+ * converted to an AhpxEvent that is forwarded to all registered forwarders.
+ *
+ * Forwarding is fire-and-forget — errors are logged but never propagate
+ * to the formatter or TurnController. This ensures that a flaky endpoint
+ * never disrupts the primary output pipeline.
+ */
+
+interface ForwardingFormatterOptions {
+    /** The inner formatter to delegate rendering to. */
+    inner: OutputFormatter;
+    /** One or more forwarders to send events to. */
+    forwarders: EventForwarder[];
+    /** Session URI to attach to forwarded events. */
+    sessionUri?: string;
+    /** Metadata tags to attach to forwarded events. */
+    tags?: Record<string, string>;
+}
+declare class ForwardingFormatter implements OutputFormatter {
+    private readonly inner;
+    private readonly forwarders;
+    private readonly tags?;
+    /** Session URI to attach to forwarded events. Can be set after construction. */
+    sessionUri?: string;
+    constructor(options: ForwardingFormatterOptions);
+    onDelta(text: string): void;
+    onReasoning(text: string): void;
+    onToolCallStart(id: string, name: string): void;
+    onToolCallDelta(id: string, paramsDelta: string): void;
+    onToolCallReady(id: string, call: ToolCallInfo): void;
+    onToolCallComplete(id: string, result: IToolCallResult): void;
+    onToolCallCancelled(id: string, reason: string): void;
+    onUsage(usage: IUsageInfo): void;
+    onTurnComplete(responseText: string): void;
+    onTurnError(error: IErrorInfo): void;
+    onTurnCancelled(): void;
+    onTitleChanged(title: string): void;
+    /**
+     * Close all forwarders, flushing any buffered events.
+     *
+     * Call this when the session/turn is done to ensure all events
+     * have been delivered.
+     */
+    close(): Promise<void>;
+    private emit;
+}
+
+/**
+ * AuthHandler — Handles AHP authentication flow.
+ *
+ * When a server sends an `authRequired` notification, the handler:
+ *   1. Checks for a stored token (from ~/.ahpx/auth.json)
+ *   2. Checks environment variable (AHPX_TOKEN)
+ *   3. Uses a CLI-provided token (--token flag)
+ *   4. Prompts the user interactively (if TTY available)
+ *   5. Stores successful tokens for future use
+ *
+ * Tokens are stored with restrictive file permissions (0600).
+ */
+
+interface AuthHandlerOptions {
+    /** Explicit token (from --token flag) */
+    token?: string;
+    /** Config directory override (for testing) */
+    configDir?: string;
+    /** Whether interactive prompting is allowed */
+    interactive?: boolean;
+}
+/**
+ * Handles AHP authentication: token storage, lookup, and delivery.
+ */
+declare class AuthHandler {
+    private readonly client;
+    private readonly configDir;
+    private readonly explicitToken;
+    private readonly interactive;
+    constructor(client: AhpClient, options?: AuthHandlerOptions);
+    /**
+     * Handle an authRequired notification — find a token and authenticate.
+     * Returns true if authentication succeeded, false otherwise.
+     */
+    handleAuthRequired(resource: IProtectedResourceMetadata): Promise<boolean>;
+    /**
+     * Store a token for a resource in ~/.ahpx/auth.json.
+     * File is created with 0600 permissions.
+     */
+    storeToken(resourceUri: string, token: string): Promise<void>;
+    /**
+     * Load a stored token for a resource.
+     */
+    loadToken(resourceUri: string): Promise<string | undefined>;
+    /**
+     * Try to authenticate with the server.
+     */
+    private tryAuthenticate;
+    /**
+     * Prompt the user for a token interactively.
+     */
+    private promptForToken;
+}
+
+/**
+ * Server Health Checker — probes AHP servers for health status.
+ *
+ * Each health check connects, initializes, reads root state, and disconnects.
+ * Stateless per-check — no long-lived connections.
+ */
+interface ServerHealth {
+    name: string;
+    url: string;
+    status: "healthy" | "degraded" | "unreachable";
+    latencyMs: number;
+    protocolVersion?: number;
+    agents: {
+        provider: string;
+        models: string[];
+    }[];
+    activeSessions: number;
+    checkedAt: string;
+    error?: string;
+}
+declare class HealthChecker {
+    private readonly _defaultTimeout;
+    constructor(options?: {
+        timeout?: number;
+    });
+    /** Check a single server's health. */
+    check(url: string, name: string, options?: {
+        timeout?: number;
+        token?: string;
+    }): Promise<ServerHealth>;
+    /** Check all servers concurrently. */
+    checkAll(connections: Array<{
+        name: string;
+        url: string;
+        token?: string;
+    }>): Promise<ServerHealth[]>;
+}
+
+/**
+ * Connection Store — Manages named AHP server connection profiles.
+ *
+ * Profiles are stored in `~/.ahpx/connections.json` with atomic writes
+ * (write to temp + rename) to prevent corruption.
+ */
+interface ConnectionProfile {
+    /** Unique display name for this connection */
+    name: string;
+    /** WebSocket URL (ws:// or wss://) */
+    url: string;
+    /** Optional authentication token */
+    token?: string;
+    /** Whether this is the default connection */
+    default?: boolean;
+    /** Optional tags for server grouping (e.g., ['gpu', 'cloud']) */
+    tags?: string[];
+}
+
+/**
+ * Fleet Manager — manages multiple AHP servers with health-aware routing.
+ *
+ * Provides server selection strategies (least-sessions, round-robin, random,
+ * preferred) and filters by provider, model, or tag. Caches health data and
+ * refreshes on demand.
+ */
+
+type RoutingStrategy = "least-sessions" | "round-robin" | "random" | "preferred";
+interface FleetManagerOptions {
+    connections: ConnectionProfile[];
+    strategy?: RoutingStrategy;
+    preferredServer?: string;
+    /** Tag-to-server-name mapping, e.g. { gpu: ['cloud-1'], local: ['laptop'] } */
+    tags?: Record<string, string[]>;
+    healthCheckTimeout?: number;
+}
+interface ServerRequirements {
+    provider?: string;
+    model?: string;
+    tag?: string;
+}
+declare class FleetManager {
+    private readonly _connections;
+    private readonly _strategy;
+    private readonly _preferredServer;
+    private readonly _tags;
+    private readonly _checker;
+    private _healthCache;
+    private _roundRobinIndex;
+    constructor(options: FleetManagerOptions);
+    /** Pick the best server for a dispatch based on strategy and requirements. */
+    selectServer(requirements?: ServerRequirements): Promise<{
+        name: string;
+        url: string;
+    }>;
+    /** Get health for all servers (cached). */
+    getHealth(): Promise<ServerHealth[]>;
+    /** Refresh health cache by checking all servers. */
+    refresh(): Promise<void>;
+    private _applyStrategy;
+    private _leastSessions;
+}
+
+/**
+ * Session Store — Persists local session metadata as individual JSON files.
+ *
+ * Each session is stored as `~/.ahpx/sessions/<id>.json`, using atomic
+ * writes (temp file + rename) to prevent corruption.
+ */
+/** Lightweight summary of a single turn, stored locally for offline history. */
+interface TurnSummary {
+    /** Turn identifier (UUID from the AHP action). */
+    turnId: string;
+    /** First 200 characters of the user's message. */
+    userMessage: string;
+    /** First 200 characters of the agent's response. */
+    responsePreview: string;
+    /** Number of tool calls made during this turn. */
+    toolCallCount: number;
+    /** Token usage, if reported by the server. */
+    tokenUsage?: {
+        input: number;
+        output: number;
+        model?: string;
+    };
+    /** Final state of the turn. */
+    state: "complete" | "cancelled" | "error";
+    /** ISO 8601 timestamp when the turn completed. */
+    timestamp: string;
+}
+interface SessionRecord {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** AHP session URI (e.g. "copilot:/<uuid>") */
+    sessionUri: string;
+    /** Name of the saved connection this session belongs to */
+    serverName: string;
+    /** WebSocket URL (preserved in case the connection profile is removed) */
+    serverUrl: string;
+    /** Agent provider (e.g. "copilot") */
+    provider: string;
+    /** Model used for this session */
+    model?: string;
+    /** User-given name for named sessions */
+    name?: string;
+    /** Working directory when the session was created */
+    workingDirectory?: string;
+    /** Nearest git root directory (for directory-walk scoping) */
+    gitRoot?: string;
+    /** Server-generated session title */
+    title?: string;
+    /** Session lifecycle status */
+    status: "active" | "closed";
+    /** ISO 8601 timestamp of creation */
+    createdAt: string;
+    /** ISO 8601 timestamp when session was closed */
+    closedAt?: string;
+    /** ISO 8601 timestamp of the last prompt sent */
+    lastPromptAt?: string;
+    /** Local turn history (lightweight summaries, capped at MAX_LOCAL_TURNS). */
+    turns?: TurnSummary[];
+}
+interface SessionFilter {
+    /** Filter by status */
+    status?: "active" | "closed";
+    /** Filter by server name */
+    serverName?: string;
+    /** Filter by working directory (exact match) */
+    workingDirectory?: string;
+    /** Filter by user-given session name */
+    name?: string;
+}
+/** Truncate a string to the preview limit, appending ellipsis if needed. */
+declare function truncatePreview(str: string, maxLen?: number): string;
+/** Build a TurnSummary from a completed turn result. */
+declare function buildTurnSummary(result: {
+    turnId: string;
+    responseText: string;
+    toolCalls: number;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        model?: string;
+    };
+    state: "complete" | "cancelled" | "error";
+    userMessage: string;
+}): TurnSummary;
+declare class SessionStore {
+    private readonly sessionsDir;
+    constructor(configDir?: string);
+    /** Ensure the sessions directory exists. */
+    private ensureDir;
+    /** Path to a session record file. Validates ID to prevent path traversal. */
+    private filePath;
+    /** Validate that a session ID is safe for use in file paths (no traversal). */
+    private validateId;
+    /**
+     * Save a session record to disk. Creates a new file or overwrites an existing one.
+     * Uses atomic writes (temp file + rename).
+     */
+    save(record: SessionRecord): Promise<void>;
+    /** Get a session record by ID, or undefined if not found. */
+    get(id: string): Promise<SessionRecord | undefined>;
+    /**
+     * List session records, optionally filtered.
+     * Returns records sorted by createdAt descending (newest first).
+     */
+    list(filter?: SessionFilter): Promise<SessionRecord[]>;
+    /**
+     * Update specific fields on an existing session record.
+     * Returns the updated record, or undefined if not found.
+     */
+    update(id: string, updates: Partial<Omit<SessionRecord, "id">>): Promise<SessionRecord | undefined>;
+    /**
+     * Soft-close a session: set status='closed' and record the timestamp.
+     * The record is preserved for history.
+     * Returns the updated record, or undefined if not found.
+     */
+    close(id: string): Promise<SessionRecord | undefined>;
+    /**
+     * Append a turn summary to a session record's local history.
+     * Caps the history at MAX_LOCAL_TURNS entries (oldest removed first).
+     * Returns the updated record, or undefined if not found.
+     */
+    appendTurn(id: string, turn: TurnSummary): Promise<SessionRecord | undefined>;
+    /**
+     * Find a session by scope: matching serverName, workingDirectory, and optional name.
+     * Only returns active sessions.
+     */
+    getByScope(options: {
+        serverName: string;
+        workingDirectory: string;
+        name?: string;
+    }): Promise<SessionRecord | undefined>;
+}
+
+/**
+ * Session Persistence — Bridge between local SessionStore and live AHP server.
+ *
+ * Handles resuming sessions from local records, saving turn summaries after
+ * each prompt, and syncing local state with server-side session lists.
+ */
+
+/** Outcome of attempting to resume a session on a server. */
+type ResumeOutcome = {
+    status: "resumed";
+} | {
+    status: "not_found";
+} | {
+    status: "error";
+    message: string;
+};
+/** Result of syncing local records with a server. */
+interface SyncResult {
+    /** Session URIs found on server but not in local store. */
+    added: string[];
+    /** Session IDs in local store whose sessions no longer exist on server. */
+    removed: string[];
+    /** Session IDs where title or status diverged. */
+    updated: string[];
+}
+declare class SessionPersistence {
+    private readonly store;
+    constructor(store: SessionStore);
+    /**
+     * Resume a locally-stored session on a connected server.
+     *
+     * Subscribes to the session URI and verifies it is still alive. Returns
+     * a ResumeOutcome indicating whether the session was found.
+     */
+    resume(record: SessionRecord, client: AhpClient): Promise<ResumeOutcome>;
+    /**
+     * Save a turn summary to the local session record after a prompt completes.
+     */
+    saveTurn(recordId: string, result: {
+        turnId: string;
+        responseText: string;
+        toolCalls: number;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+            model?: string;
+        };
+        state: "complete" | "cancelled" | "error";
+        userMessage: string;
+    }): Promise<SessionRecord | undefined>;
+    /**
+     * Sync local session records for a server with the server's actual state.
+     *
+     * Compares locally-active records against the server's session list to
+     * find sessions that were added remotely, disposed remotely, or updated.
+     */
+    sync(client: AhpClient, serverName: string): Promise<SyncResult>;
+}
+
+/**
+ * URI utility functions for converting between file URIs and filesystem paths.
+ *
+ * These functions handle both Unix and Windows paths correctly regardless of
+ * the platform they run on — critical for ahpx which may run on macOS/Linux
+ * while targeting remote Windows servers via `--cwd`.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8089 — The "file" URI Scheme
+ */
+/**
+ * Ensure a filesystem path or URI string is a proper `file://` URI.
+ *
+ * | Input                       | Output                              |
+ * |-----------------------------|-------------------------------------|
+ * | `C:\Users\tyler\Code`       | `file:///C:/Users/tyler/Code`       |
+ * | `C:/Users/tyler/Code`       | `file:///C:/Users/tyler/Code`       |
+ * | `/Users/tyler/Code`         | `file:///Users/tyler/Code`          |
+ * | `file:///C:/Users/tyler`    | `file:///C:/Users/tyler` (unchanged)|
+ * | `copilot:/session-1`        | `copilot:/session-1` (unchanged)    |
+ * | `""` (empty)                | `""` (unchanged)                    |
+ *
+ * Backslashes are normalized to forward slashes. Spaces and other reserved
+ * characters in path components are percent-encoded.
+ */
+declare function ensureFileUri(pathOrUri: string): string;
+/**
+ * Convert a `file://` URI to a display-friendly filesystem path.
+ *
+ * | Input                           | Output                    |
+ * |---------------------------------|---------------------------|
+ * | `file:///C:/Users/tyler/Code`   | `C:/Users/tyler/Code`     |
+ * | `file:///Users/tyler/Code`      | `/Users/tyler/Code`       |
+ * | `file:///C%3A/Users/tyler`      | `C:/Users/tyler`          |
+ * | `copilot:/session-1`            | `copilot:/session-1`      |
+ * | `/plain/path`                   | `/plain/path`             |
+ *
+ * Percent-encoded characters are decoded. Windows drive letters are detected
+ * and the leading slash is stripped so the path starts with `C:`.
+ */
+declare function fileUriToDisplayPath(uri: string): string;
+
+export { ActionType, ActiveClientManager, AhpClient, type AhpClientEvents, type AhpClientOptions, type AhpxEvent, AuthHandler, type AuthHandlerOptions, ConnectionPool, type ConnectionPoolOptions, type ConnectionProfile, ContentEncoding, type EventForwarder, FleetManager, type FleetManagerOptions, ForwardingFormatter, type ForwardingFormatterOptions, HealthChecker, type IActionEnvelope, type IActiveTurn, type IAgentInfo, type ICreateSessionParams, type ICustomizationRef, type IErrorInfo, type IFetchTurnsResult, type IInitializeResult, type IListSessionsResult, type IMarkdownResponsePart, type IPendingMessage, type IProtocolNotification, type IReasoningResponsePart, type IResourceCopyParams, type IResourceCopyResult, type IResourceDeleteParams, type IResourceDeleteResult, type IResourceListResult, type IResourceMoveParams, type IResourceMoveResult, type IResourceReadResult, type IResourceWriteParams, type IResourceWriteResult, type IResponsePart, type IRootState, type ISessionCustomization, type ISessionForkSource, type ISessionState, type ISessionSummary, type ISnapshot, type IStateAction, type ISubscribeResult, type IToolAnnotations, type IToolCallResponsePart, type IToolCallState, type IToolDefinition, type ITurn, type IUsageInfo, type IUserMessage, type Icon, type OpenSessionOptions, PendingMessageKind, type PromptOptions, ProtocolLayer, type ProtocolLayerOptions, ReconnectManager, type ReconnectOptions, type ReconnectOutcome, ResponsePartKind, type ResumeOutcome, type RoutingStrategy, RpcError, RpcTimeoutError, type ServerHealth, type ServerRequirements, type SessionFilter, SessionHandle, type SessionHandleEvents, SessionLifecycle, SessionPersistence, type SessionRecord, SessionStatus, SessionStore, type TurnResult as SessionTurnResult, StateMirror, type SyncResult, ToolCallStatus, Transport, type TransportOptions, type TurnSummary, type URI, WebSocketForwarder, type WebSocketForwarderOptions, WebhookForwarder, type WebhookForwarderOptions, buildTurnSummary, ensureFileUri, fileUriToDisplayPath, truncatePreview };