@linxiraos/pi-utils 1.0.0

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>;
+}

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

@@ -0,0 +1,41 @@
+import type { ForkSessionResponse, LoadSessionResponse, NewSessionResponse, PromptResponse, SessionNotification } from "./protocol.js";
+/** Validation failure compatible with the used Zod error surface. */
+export interface ValidationError {
+    issues: Array<{
+        path: Array<string | number>;
+        message: string;
+    }>;
+}
+/** Successful validation result. */
+export interface ValidationSuccess<T> {
+    success: true;
+    data: T;
+}
+/** Failed validation result. */
+export interface ValidationFailure {
+    success: false;
+    error: ValidationError;
+}
+/** Runtime validator compatible with the used schema call shape. */
+export interface Validator<T> {
+    safeParse(value: unknown): ValidationSuccess<T> | ValidationFailure;
+    parse(value: unknown): T;
+}
+/** Validator for new-session responses. */
+export declare const zNewSessionResponse: Validator<NewSessionResponse>;
+/** Validator for load-session responses. */
+export declare const zLoadSessionResponse: Validator<LoadSessionResponse>;
+/** Validator for fork-session responses. */
+export declare const zForkSessionResponse: Validator<ForkSessionResponse>;
+/** Validator for prompt responses. */
+export declare const zPromptResponse: Validator<PromptResponse>;
+/** Validator for session notifications. */
+export declare const zSessionNotification: Validator<SessionNotification>;
+/** ACP runtime validators. */
+export declare const schema: {
+    readonly zNewSessionResponse: Validator<NewSessionResponse>;
+    readonly zLoadSessionResponse: Validator<LoadSessionResponse>;
+    readonly zForkSessionResponse: Validator<ForkSessionResponse>;
+    readonly zPromptResponse: Validator<PromptResponse>;
+    readonly zSessionNotification: Validator<SessionNotification>;
+};

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

@@ -0,0 +1,8 @@
+import type { AnyMessage } from "./transport.js";
+/** Bidirectional JSON-RPC message transport. */
+export interface Stream {
+    writable: WritableStream<AnyMessage>;
+    readable: ReadableStream<AnyMessage>;
+}
+/** Converts byte-oriented newline-delimited JSON streams to an ACP message transport. */
+export declare function ndJsonStream(output: WritableStream<Uint8Array>, input: ReadableStream<Uint8Array>): Stream;

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

@@ -0,0 +1,81 @@
+import type { MaybePromise } from "./protocol.js";
+import type { Stream } from "./stream.js";
+/** JSON-RPC request identifier. */
+export type JsonRpcId = string | number | null;
+/** JSON-RPC request. */
+export interface AnyRequest {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+/** JSON-RPC notification. */
+export interface AnyNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+}
+/** JSON-RPC error payload. */
+export interface ErrorResponse {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/** JSON-RPC response. */
+export type AnyResponse = {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+} & ({
+    result: unknown;
+} | {
+    error: ErrorResponse;
+});
+/** Any JSON-RPC wire message. */
+export type AnyMessage = AnyRequest | AnyNotification | AnyResponse;
+/** Error returned by a JSON-RPC peer or handler. */
+export declare class RequestError extends Error {
+    /** JSON-RPC error code. */
+    readonly code: number;
+    /** Optional protocol error data. */
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+    /** Creates a JSON parse error. */
+    static parseError(data?: unknown, additionalMessage?: string): RequestError;
+    /** Creates an invalid-request error. */
+    static invalidRequest(data?: unknown, additionalMessage?: string): RequestError;
+    /** Creates a method-not-found error. */
+    static methodNotFound(method: string): RequestError;
+    /** Creates an invalid-parameters error. */
+    static invalidParams(data?: unknown, additionalMessage?: string): RequestError;
+    /** Creates an internal error. */
+    static internalError(data?: unknown, additionalMessage?: string): RequestError;
+    /** Creates a cancellation error. */
+    static requestCancelled(data?: unknown, additionalMessage?: string): RequestError;
+    /** Creates an authentication-required error. */
+    static authRequired(data?: unknown, additionalMessage?: string): RequestError;
+    /** Creates a resource-not-found error. */
+    static resourceNotFound(uri?: string): RequestError;
+    /** Converts this error into a JSON-RPC result. */
+    toResult(): {
+        error: ErrorResponse;
+    };
+    /** Converts this error into a JSON-RPC error payload. */
+    toErrorResponse(): ErrorResponse;
+}
+type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
+/** Correlated bidirectional JSON-RPC connection. */
+export declare class RpcConnection {
+    #private;
+    constructor(stream: Stream, dispatcher: Dispatcher);
+    /** Signal aborted when the stream closes. */
+    get signal(): AbortSignal;
+    /** Promise resolved when the stream closes. */
+    get closed(): Promise<void>;
+    /** Sends a correlated JSON-RPC request. */
+    request<Response>(method: string, params?: unknown): Promise<Response>;
+    /** Sends a JSON-RPC notification. */
+    notify(method: string, params?: unknown): Promise<void>;
+    /** Closes the connection and rejects outstanding requests. */
+    close(error?: unknown): void;
+}
+export {};

package/dist/types/acp.d.ts

@@ -0,0 +1,6 @@
+/** Behavior-compatible reimplementation of @agentclientprotocol/sdk's used surface. */
+export * from "./acp/connection.js";
+export * from "./acp/protocol.js";
+export * from "./acp/schema.js";
+export * from "./acp/stream.js";
+export * from "./acp/transport.js";

package/dist/types/async.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Wrap a promise with a timeout and optional abort signal.
+ * Rejects with the given message if the timeout fires first.
+ * Cleans up all listeners on settlement.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T>;
+/**
+ * Coalesces rapid-fire writes into one deferred batch. `push` queues a value
+ * and returns a promise for the batch flush; the first push of a batch arms a
+ * timer (`delayMs`, or a microtask at 0), and every push before it fires joins
+ * the same batch and shares the same promise. Used to keep hot paths off
+ * synchronous storage (prompt history, model perf).
+ */
+export declare class AsyncDrain<T> {
+    #private;
+    readonly delayMs: number;
+    constructor(delayMs?: number);
+    /** Queue `value`; `hnd` receives the whole batch when the window closes. */
+    push(value: T, hnd: (values: T[]) => Promise<void> | void): Promise<void>;
+}