@oh-my-pi/pi-utils 17.2.8 → 17.2.10

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## [Unreleased]
 
+## [17.2.10] - 2026-08-06
+
+### Added
+
+- Introduced zero-dependency in-house modules replacing external packages, importable via `@oh-my-pi/pi-utils/<module>`: `acp` (Agent Client Protocol), `browsers` (Chrome for Testing discovery/install), `chalk` (ANSI styling), `dates` (date formatting), `dom` (HTML parser, WHATWG DOM subset, and CSS selectors), `docx` (DOCX to HTML), `headers` (browser header generation), `lru` (LRU cache), `marked` (GFM markdown lexer/parser), `readability` (article extraction), `template` (Handlebars-compatible templating), `turndown` (HTML to Markdown), `vterm` (headless terminal emulator), and `xml` (XML parser).
+- Added postmortem fatal recovery hint providers to allow applications to print actionable recovery commands before cleanup starts.
+
+### Changed
+
+- Rewrote the logger file backend in-house, maintaining the identical line format, daily rotation, and pruning behavior without external dependencies.
+
+### Fixed
+
+- Fixed PowerShell (`powershell.exe` / `pwsh`) support when used as a custom `shellPath` by correctly passing `-NoLogo -Command` (and `-NoProfile` under `PI_BASH_NO_LOGIN`) instead of POSIX flags.
+- Fixed the in-house `marked` list tokenizer consuming the trailing blank line into the list token when the next top-level line was a plain paragraph. The blank now always becomes a separate `space` token (matching real marked), so a list's token shape no longer depends on what follows it — restoring the TUI streaming lexer's freeze invariant — and a list followed by a paragraph is tight, not loose, per CommonMark.
+- Added the missing Handlebars built-in `lookup` helper to the in-house `template` engine (`{{lookup obj key}}`, proto-safe property access; a user-registered `lookup` helper still takes precedence).
+
+### Removed
+
+- Removed external dependencies on `handlebars`, `winston`, and `winston-daily-rotate-file`.
+
+## [17.2.9] - 2026-08-05
+
+### Added
+
+- Added a public `compareVersions` utility (`@oh-my-pi/pi-utils`) that compares two version strings with SemVer-2.0 prerelease ordering, build-metadata stripping, and numeric segment comparison without float overflow; never throws.
+
+### Fixed
+
+- Honor the current process `PATH` when caching executable lookups, preventing stale tool paths after environment reloads.
+- Parsed account-cap reset windows such as “Your limit will reset in 13 minutes” so credential backoff honors the provider's full reset duration.
+
 ## [17.2.6] - 2026-08-03
 
 ### Added

package/dist/types/acp/connection.d.ts

@@ -0,0 +1,118 @@
+import type { Agent, AuthenticateRequest, AuthenticateResponse, CloseSessionRequest, CloseSessionResponse, CompleteElicitationNotification, CreateElicitationRequest, CreateElicitationResponse, CreateTerminalRequest, ForkSessionRequest, ForkSessionResponse, InitializeRequest, InitializeResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, MaybePromise, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, RequestPermissionRequest, RequestPermissionResponse, ResumeSessionRequest, ResumeSessionResponse, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, TerminalActionResponse, TerminalOutputResponse, WaitForTerminalExitResponse, WriteTextFileRequest, WriteTextFileResponse } from "./protocol.js";
+import type { Stream } from "./stream.js";
+import { RpcConnection } from "./transport.js";
+/** Terminal creation response returned by a client. */
+export interface CreateTerminalResponse {
+    terminalId: string;
+}
+/** Client callbacks handled by a client-side connection. */
+export interface Client {
+    requestPermission(params: RequestPermissionRequest): MaybePromise<RequestPermissionResponse>;
+    sessionUpdate(params: SessionNotification): MaybePromise<void>;
+    readTextFile?(params: ReadTextFileRequest): MaybePromise<ReadTextFileResponse>;
+    writeTextFile?(params: WriteTextFileRequest): MaybePromise<WriteTextFileResponse | void>;
+    createTerminal?(params: CreateTerminalRequest): MaybePromise<CreateTerminalResponse>;
+    terminalOutput?(params: {
+        sessionId: string;
+        terminalId: string;
+    }): MaybePromise<TerminalOutputResponse>;
+    waitForTerminalExit?(params: {
+        sessionId: string;
+        terminalId: string;
+    }): MaybePromise<WaitForTerminalExitResponse>;
+    killTerminal?(params: {
+        sessionId: string;
+        terminalId: string;
+    }): MaybePromise<TerminalActionResponse | void>;
+    releaseTerminal?(params: {
+        sessionId: string;
+        terminalId: string;
+    }): MaybePromise<TerminalActionResponse | void>;
+    unstable_createElicitation?(params: CreateElicitationRequest): MaybePromise<CreateElicitationResponse>;
+    unstable_completeElicitation?(params: CompleteElicitationNotification): MaybePromise<void>;
+    extMethod?(method: string, params: Record<string, unknown>): MaybePromise<Record<string, unknown>>;
+    extNotification?(method: string, params: Record<string, unknown>): MaybePromise<void>;
+}
+/** Agent-side ACP connection. */
+export declare class AgentSideConnection {
+    #private;
+    constructor(toAgent: (connection: AgentSideConnection) => Agent, stream: Stream);
+    /** Signal aborted when the transport closes. */
+    get signal(): AbortSignal;
+    /** Promise resolved when the transport closes. */
+    get closed(): Promise<void>;
+    /** Sends a session update notification. */
+    sessionUpdate(params: SessionNotification): Promise<void>;
+    /** Requests permission from the client. */
+    requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+    /** Reads a client-side text file. */
+    readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
+    /** Writes a client-side text file. */
+    writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
+    /** Creates a client terminal and returns its control handle. */
+    createTerminal(params: CreateTerminalRequest): Promise<TerminalHandle>;
+    /** Creates an interactive elicitation on the client. */
+    unstable_createElicitation(params: CreateElicitationRequest): Promise<CreateElicitationResponse>;
+    /** Notifies a client that URL elicitation completed. */
+    unstable_completeElicitation(params: CompleteElicitationNotification): Promise<void>;
+    /** Sends a custom request. */
+    request<Response = unknown, Params = unknown>(method: string, params?: Params): Promise<Response>;
+    /** Sends a custom notification. */
+    notify<Params = unknown>(method: string, params?: Params): Promise<void>;
+    /** Sends a legacy extension request. */
+    extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Sends a legacy extension notification. */
+    extNotification(method: string, params: Record<string, unknown>): Promise<void>;
+}
+/** Handle for controlling a client-owned terminal. */
+export declare class TerminalHandle {
+    #private;
+    /** Client terminal identifier. */
+    readonly id: string;
+    constructor(id: string, sessionId: string, connection: RpcConnection);
+    /** Gets current terminal output. */
+    currentOutput(): Promise<TerminalOutputResponse>;
+    /** Waits for terminal exit. */
+    waitForExit(): Promise<WaitForTerminalExitResponse>;
+    /** Kills the terminal. */
+    kill(): Promise<TerminalActionResponse>;
+    /** Releases the terminal. */
+    release(): Promise<TerminalActionResponse | void>;
+    /** Releases the terminal during async disposal. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** Client-side ACP connection used to call an agent. */
+export declare class ClientSideConnection {
+    #private;
+    constructor(toClient: (connection: ClientSideConnection) => Client, stream: Stream);
+    /** Signal aborted when the transport closes. */
+    get signal(): AbortSignal;
+    /** Promise resolved when the transport closes. */
+    get closed(): Promise<void>;
+    /** Initializes protocol capabilities. */
+    initialize(params: InitializeRequest): Promise<InitializeResponse>;
+    /** Authenticates with an agent. */
+    authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse>;
+    /** Creates a session. */
+    newSession(params: NewSessionRequest): Promise<NewSessionResponse>;
+    /** Loads a session. */
+    loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse>;
+    /** Lists sessions. */
+    listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse>;
+    /** Resumes a session. */
+    resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse>;
+    /** Forks a session. */
+    unstable_forkSession(params: ForkSessionRequest): Promise<ForkSessionResponse>;
+    /** Closes a session. */
+    closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse>;
+    /** Sets a session mode. */
+    setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse>;
+    /** Sets a session config option. */
+    setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
+    /** Sends a prompt. */
+    prompt(params: PromptRequest): Promise<PromptResponse>;
+    /** Cancels an active prompt. */
+    cancel(params: {
+        sessionId: string;
+    }): Promise<void>;
+}

package/dist/types/acp/protocol.d.ts

@@ -0,0 +1,526 @@
+/** Behavior-compatible reimplementation of @agentclientprotocol/sdk's used protocol surface. */
+/** Metadata reserved for protocol extensions. */
+export interface Meta {
+    _meta?: Record<string, unknown> | null;
+}
+/** A value which may be produced asynchronously. */
+export type MaybePromise<T> = T | Promise<T>;
+/** ACP protocol version identifier. */
+export type ProtocolVersion = number;
+/** Current ACP protocol version. */
+export declare const PROTOCOL_VERSION = 1;
+/** Conversation session identifier. */
+export type SessionId = string;
+/** Tool call identifier. */
+export type ToolCallId = string;
+/** ACP tool category. */
+export type ToolKind = "read" | "edit" | "delete" | "move" | "search" | "execute" | "think" | "fetch" | "switch_mode" | "other";
+/** ACP tool execution state. */
+export type ToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+/** ACP prompt stop reason. */
+export type StopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+/** ACP permission choice kind. */
+export type PermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+/** Text content block. */
+export interface TextContent extends Meta {
+    type: "text";
+    text: string;
+}
+/** Image content block. */
+export interface ImageContent extends Meta {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+/** Audio content block. */
+export interface AudioContent extends Meta {
+    type: "audio";
+    data: string;
+    mimeType: string;
+}
+/** Resource link content block. */
+export interface ResourceLink extends Meta {
+    type: "resource_link";
+    uri: string;
+    name?: string;
+    title?: string;
+    mimeType?: string | null;
+    description?: string | null;
+    size?: number | null;
+}
+/** Text or blob resource embedded in a prompt. */
+export type EmbeddedResourceValue = ({
+    uri: string;
+    text: string;
+    mimeType?: string;
+} | {
+    uri: string;
+    blob: string;
+    mimeType?: string;
+}) & Meta;
+/** Embedded resource content block. */
+export interface EmbeddedResource extends Meta {
+    type: "resource";
+    resource: EmbeddedResourceValue;
+}
+/** Displayable ACP content. */
+export type ContentBlock = TextContent | ImageContent | AudioContent | ResourceLink | EmbeddedResource;
+/** Content wrapper used by tool calls. */
+export interface ToolContent extends Meta {
+    type: "content";
+    content: ContentBlock;
+}
+/** File diff emitted by a tool call. */
+export interface ToolDiff extends Meta {
+    type: "diff";
+    path: string;
+    oldText?: string | null;
+    newText: string;
+}
+/** Terminal reference emitted by a tool call. */
+export interface ToolTerminal extends Meta {
+    type: "terminal";
+    terminalId: string;
+}
+/** Tool call output item. */
+export type ToolCallContent = ToolContent | ToolDiff | ToolTerminal;
+/** File location associated with a tool call. */
+export interface ToolCallLocation extends Meta {
+    path: string;
+    line?: number | null;
+}
+/** Initial tool call notification. */
+export interface ToolCall extends Meta {
+    toolCallId: ToolCallId;
+    title: string;
+    kind?: ToolKind | null;
+    status?: ToolCallStatus | null;
+    content?: ToolCallContent[] | null;
+    locations?: ToolCallLocation[] | null;
+    rawInput?: unknown;
+    rawOutput?: unknown;
+}
+/** Partial update to a tool call. */
+export interface ToolCallUpdate extends Meta {
+    toolCallId: ToolCallId;
+    title?: string | null;
+    kind?: ToolKind | null;
+    status?: ToolCallStatus | null;
+    content?: ToolCallContent[] | null;
+    locations?: ToolCallLocation[] | null;
+    rawInput?: unknown;
+    rawOutput?: unknown;
+}
+/** Permission option presented by the client. */
+export interface PermissionOption extends Meta {
+    optionId: string;
+    name: string;
+    kind: PermissionOptionKind;
+}
+/** Request for permission to execute a tool call. */
+export interface RequestPermissionRequest extends Meta {
+    sessionId: SessionId;
+    toolCall: ToolCallUpdate;
+    options: PermissionOption[];
+}
+/** Permission request response. */
+export interface RequestPermissionResponse extends Meta {
+    outcome: {
+        outcome: "cancelled";
+    } | {
+        outcome: "selected";
+        optionId: string;
+    };
+}
+/** Client filesystem capabilities. */
+export interface FileSystemCapabilities {
+    readTextFile?: boolean;
+    writeTextFile?: boolean;
+}
+/** Capabilities advertised by an ACP client. */
+export interface ClientCapabilities {
+    fs?: FileSystemCapabilities;
+    terminal?: boolean;
+    auth?: {
+        terminal?: boolean;
+    };
+    elicitation?: {
+        form?: Record<string, unknown>;
+        url?: Record<string, unknown>;
+    };
+    _meta?: Record<string, unknown>;
+}
+/** Implementation identity sent during initialization. */
+export interface Implementation {
+    name: string;
+    version: string;
+    title?: string;
+}
+/** Initialization request. */
+export interface InitializeRequest extends Meta {
+    protocolVersion: ProtocolVersion;
+    clientCapabilities?: ClientCapabilities;
+    clientInfo?: Implementation | null;
+}
+/** Authentication method using an environment variable. */
+export interface AuthMethodEnvVar extends Meta {
+    type: "env_var";
+    id: string;
+    name: string;
+    description?: string | null;
+    variable: string;
+}
+/** Authentication method using a terminal command. */
+export interface AuthMethodTerminal extends Meta {
+    type: "terminal";
+    id: string;
+    name: string;
+    description?: string | null;
+    command?: string;
+    args?: string[];
+}
+/** Authentication method handled by the agent. */
+export interface AuthMethodAgent extends Meta {
+    type?: "agent";
+    id: string;
+    name: string;
+    description?: string | null;
+}
+/** Authentication method advertised by an agent. */
+export type AuthMethod = AuthMethodEnvVar | AuthMethodTerminal | AuthMethodAgent;
+/** Initialization response. */
+export interface InitializeResponse extends Meta {
+    protocolVersion: ProtocolVersion;
+    agentCapabilities?: Record<string, unknown>;
+    authMethods?: AuthMethod[];
+    agentInfo?: Implementation | null;
+}
+/** Authentication request. */
+export interface AuthenticateRequest extends Meta {
+    methodId: string;
+}
+/** Authentication response. */
+export interface AuthenticateResponse extends Meta {
+}
+/** ACP MCP server configuration. */
+export type McpServer = ({
+    type?: "stdio";
+    name: string;
+    command: string;
+    args?: string[];
+    env: Array<{
+        name: string;
+        value: string;
+    }>;
+} | {
+    type: "http" | "sse" | "acp";
+    name: string;
+    url: string;
+    headers: Array<{
+        name: string;
+        value: string;
+    }>;
+}) & Meta;
+/** Session mode descriptor. */
+export interface SessionMode extends Meta {
+    id: string;
+    name: string;
+    description?: string | null;
+}
+/** Current session mode and available choices. */
+export interface SessionModeState extends Meta {
+    currentModeId: string;
+    availableModes: SessionMode[];
+}
+/** Select configuration value. */
+export interface SessionConfigSelectOption extends Meta {
+    value: string;
+    name: string;
+    description?: string | null;
+}
+/** Session configuration option. */
+export type SessionConfigOption = ({
+    type: "select";
+    currentValue: string;
+    options: SessionConfigSelectOption[];
+} | {
+    type: "boolean";
+    currentValue: boolean;
+}) & {
+    id: string;
+    name: string;
+    description?: string | null;
+    category?: string | null;
+} & Meta;
+/** Shared fields for creating or restoring a session. */
+export interface SessionSetupRequest extends Meta {
+    cwd: string;
+    mcpServers: McpServer[];
+    additionalDirectories?: string[];
+}
+/** New-session request. */
+export interface NewSessionRequest extends SessionSetupRequest {
+}
+/** New-session response. */
+export interface NewSessionResponse extends Meta {
+    sessionId: SessionId;
+    modes?: SessionModeState | null;
+    configOptions?: SessionConfigOption[] | null;
+}
+/** Load-session request. */
+export interface LoadSessionRequest extends SessionSetupRequest {
+    sessionId: SessionId;
+}
+/** Load-session response. */
+export interface LoadSessionResponse extends Meta {
+    modes?: SessionModeState | null;
+    configOptions?: SessionConfigOption[] | null;
+}
+/** Resume-session request. */
+export interface ResumeSessionRequest extends LoadSessionRequest {
+}
+/** Resume-session response. */
+export interface ResumeSessionResponse extends LoadSessionResponse {
+}
+/** Fork-session request. */
+export interface ForkSessionRequest extends LoadSessionRequest {
+}
+/** Fork-session response. */
+export interface ForkSessionResponse extends NewSessionResponse {
+}
+/** Close-session request. */
+export interface CloseSessionRequest extends Meta {
+    sessionId: SessionId;
+}
+/** Close-session response. */
+export interface CloseSessionResponse extends Meta {
+}
+/** Session-list request. */
+export interface ListSessionsRequest extends Meta {
+    cwd?: string | null;
+    cursor?: string | null;
+    additionalDirectories?: string[];
+}
+/** Session metadata. */
+export interface SessionInfo extends Meta {
+    sessionId: SessionId;
+    cwd: string;
+    additionalDirectories?: string[];
+    title?: string | null;
+    updatedAt?: string | null;
+}
+/** Session-list response. */
+export interface ListSessionsResponse extends Meta {
+    sessions: SessionInfo[];
+    nextCursor?: string | null;
+}
+/** Set-mode request. */
+export interface SetSessionModeRequest extends Meta {
+    sessionId: SessionId;
+    modeId: string;
+}
+/** Set-mode response. */
+export interface SetSessionModeResponse extends Meta {
+}
+/** Set-config request. */
+export interface SetSessionConfigOptionRequest extends Meta {
+    sessionId: SessionId;
+    configId: string;
+    value: string | boolean;
+}
+/** Set-config response. */
+export interface SetSessionConfigOptionResponse extends Meta {
+    configOptions: SessionConfigOption[];
+}
+/** Slash command advertised by an agent. */
+export interface AvailableCommand extends Meta {
+    name: string;
+    description: string;
+    input?: {
+        hint: string;
+    } | null;
+}
+/** Session plan entry. */
+export interface PlanEntry extends Meta {
+    content: string;
+    priority: "high" | "medium" | "low";
+    status: "pending" | "in_progress" | "completed";
+}
+/** Session update payload. */
+export type SessionUpdate = ({
+    sessionUpdate: "agent_message_chunk" | "agent_thought_chunk" | "user_message_chunk";
+    content: ContentBlock;
+    messageId?: string;
+} & Meta) | ({
+    sessionUpdate: "tool_call";
+} & ToolCall) | ({
+    sessionUpdate: "tool_call_update";
+} & ToolCallUpdate) | ({
+    sessionUpdate: "plan";
+    entries: PlanEntry[];
+} & Meta) | ({
+    sessionUpdate: "current_mode_update";
+    currentModeId: string;
+} & Meta) | ({
+    sessionUpdate: "config_option_update";
+    configOptions: SessionConfigOption[];
+} & Meta) | ({
+    sessionUpdate: "available_commands_update";
+    availableCommands: AvailableCommand[];
+} & Meta) | ({
+    sessionUpdate: "session_info_update";
+    title?: string | null;
+    updatedAt?: string | null;
+} & Meta) | ({
+    sessionUpdate: "usage_update";
+    size: number;
+    used: number;
+    cost?: {
+        amount: number;
+        currency: string;
+    } | null;
+} & Meta);
+/** Notification containing a session update. */
+export interface SessionNotification extends Meta {
+    sessionId: SessionId;
+    update: SessionUpdate;
+}
+/** Prompt request. */
+export interface PromptRequest extends Meta {
+    sessionId: SessionId;
+    prompt: ContentBlock[];
+}
+/** Prompt token usage. */
+export interface Usage extends Meta {
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cachedReadTokens?: number | null;
+    cachedWriteTokens?: number | null;
+    thoughtTokens?: number | null;
+}
+/** Prompt response. */
+export interface PromptResponse extends Meta {
+    stopReason: StopReason;
+    usage?: Usage | null;
+}
+/** Read-file request. */
+export interface ReadTextFileRequest extends Meta {
+    sessionId: string;
+    path: string;
+    line?: number | null;
+    limit?: number | null;
+}
+/** Read-file response. */
+export interface ReadTextFileResponse extends Meta {
+    content: string;
+}
+/** Write-file request. */
+export interface WriteTextFileRequest extends Meta {
+    sessionId: string;
+    path: string;
+    content: string;
+}
+/** Write-file response. */
+export interface WriteTextFileResponse extends Meta {
+}
+/** Create-terminal request. */
+export interface CreateTerminalRequest extends Meta {
+    sessionId: string;
+    command: string;
+    args?: string[];
+    env?: Array<{
+        name: string;
+        value: string;
+    }>;
+    cwd?: string;
+    outputByteLimit?: number;
+}
+/** Terminal output response. */
+export interface TerminalOutputResponse extends Meta {
+    output: string;
+    truncated: boolean;
+    exitStatus?: {
+        exitCode?: number | null;
+        signal?: string | null;
+    } | null;
+}
+/** Terminal exit response. */
+export interface WaitForTerminalExitResponse extends Meta {
+    exitCode?: number | null;
+    signal?: string | null;
+}
+/** Empty terminal response. */
+export interface TerminalActionResponse extends Meta {
+}
+/** Elicitation scalar value. */
+export type ElicitationContentValue = string | number | boolean | string[];
+/** Elicitation property schema. */
+export type ElicitationPropertySchema = Record<string, unknown> & {
+    type: string;
+    title?: string;
+    description?: string;
+};
+/** Elicitation creation request. */
+export type CreateElicitationRequest = ({
+    mode: "form";
+    sessionId: string;
+    message: string;
+    requestedSchema: {
+        type: "object";
+        properties: Record<string, ElicitationPropertySchema>;
+        required?: string[];
+    };
+} & Meta) | ({
+    mode: "url";
+    sessionId: string;
+    message: string;
+    url: string;
+    elicitationId: string;
+} & Meta) | ({
+    mode: string;
+    sessionId: string;
+    message: string;
+    requestedSchema?: {
+        type: "object";
+        properties: Record<string, ElicitationPropertySchema>;
+        required?: string[];
+    };
+    url?: string;
+    elicitationId?: string;
+} & Meta);
+/** Elicitation creation response. */
+export type CreateElicitationResponse = ({
+    action: "accept";
+    content: Record<string, ElicitationContentValue>;
+} & Meta) | ({
+    action: "decline" | "cancel";
+    content?: never;
+} & Meta) | ({
+    action: string;
+    content?: Record<string, ElicitationContentValue>;
+} & Meta);
+/** Completion notification for URL elicitation. */
+export interface CompleteElicitationNotification extends Meta {
+    sessionId: string;
+    elicitationId: string;
+}
+/** Agent-side request handler contract. */
+export interface Agent {
+    initialize(params: InitializeRequest): MaybePromise<InitializeResponse>;
+    newSession(params: NewSessionRequest): MaybePromise<NewSessionResponse>;
+    prompt(params: PromptRequest): MaybePromise<PromptResponse>;
+    cancel(params: {
+        sessionId: string;
+    }): MaybePromise<void>;
+    authenticate?(params: AuthenticateRequest): MaybePromise<AuthenticateResponse | void>;
+    loadSession?(params: LoadSessionRequest): MaybePromise<LoadSessionResponse | void>;
+    listSessions?(params: ListSessionsRequest): MaybePromise<ListSessionsResponse>;
+    resumeSession?(params: ResumeSessionRequest): MaybePromise<ResumeSessionResponse>;
+    unstable_forkSession?(params: ForkSessionRequest): MaybePromise<ForkSessionResponse>;
+    closeSession?(params: CloseSessionRequest): MaybePromise<CloseSessionResponse | void>;
+    setSessionMode?(params: SetSessionModeRequest): MaybePromise<SetSessionModeResponse | void>;
+    setSessionConfigOption?(params: SetSessionConfigOptionRequest): MaybePromise<SetSessionConfigOptionResponse>;
+    extMethod?(method: string, params: Record<string, unknown>): MaybePromise<Record<string, unknown>>;
+    extNotification?(method: string, params: Record<string, unknown>): MaybePromise<void>;
+}