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

package/src/acp/protocol.ts

@@ -0,0 +1,466 @@
+/** 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 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/src/acp/schema.ts

@@ -0,0 +1,160 @@
+import type {
+	ForkSessionResponse,
+	LoadSessionResponse,
+	NewSessionResponse,
+	PromptResponse,
+	SessionNotification,
+} from "./protocol";
+
+/** 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;
+}
+
+function validator<T>(check: (value: unknown) => boolean, label: string): Validator<T> {
+	return {
+		safeParse(value) {
+			return check(value)
+				? { success: true, data: value as T }
+				: { success: false, error: { issues: [{ path: [], message: `Invalid ${label}` }] } };
+		},
+		parse(value) {
+			if (!check(value)) throw new Error(`Invalid ${label}`);
+			return value as T;
+		},
+	};
+}
+
+function objectWithString(value: unknown, key: string): boolean {
+	return typeof value === "object" && value !== null && typeof (value as Record<string, unknown>)[key] === "string";
+}
+
+function validModes(value: unknown): boolean {
+	if (value === undefined || value === null) return true;
+	if (typeof value !== "object" || value === null) return false;
+	const modes = value as Record<string, unknown>;
+	return (
+		typeof modes.currentModeId === "string" &&
+		Array.isArray(modes.availableModes) &&
+		modes.availableModes.every(mode => objectWithString(mode, "id") && objectWithString(mode, "name"))
+	);
+}
+
+function sessionResponse(value: unknown, needsId: boolean): boolean {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const response = value as Record<string, unknown>;
+	if (needsId && typeof response.sessionId !== "string") return false;
+	if (!validModes(response.modes)) return false;
+	return (
+		response.configOptions === undefined || response.configOptions === null || Array.isArray(response.configOptions)
+	);
+}
+
+function contentBlock(value: unknown): boolean {
+	if (typeof value !== "object" || value === null) return false;
+	const block = value as Record<string, unknown>;
+	switch (block.type) {
+		case "text":
+			return typeof block.text === "string";
+		case "image":
+		case "audio":
+			return typeof block.data === "string" && typeof block.mimeType === "string";
+		case "resource_link":
+			return typeof block.uri === "string" && typeof block.name === "string";
+		case "resource":
+			return typeof block.resource === "object" && block.resource !== null;
+		default:
+			return false;
+	}
+}
+
+function sessionNotification(value: unknown): boolean {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const notification = value as Record<string, unknown>;
+	if (
+		typeof notification.sessionId !== "string" ||
+		typeof notification.update !== "object" ||
+		notification.update === null
+	)
+		return false;
+	const update = notification.update as Record<string, unknown>;
+	if (typeof update.sessionUpdate !== "string") return false;
+	switch (update.sessionUpdate) {
+		case "agent_message_chunk":
+		case "agent_thought_chunk":
+		case "user_message_chunk":
+			return contentBlock(update.content);
+		case "tool_call":
+			return typeof update.toolCallId === "string" && typeof update.title === "string";
+		case "tool_call_update":
+			return typeof update.toolCallId === "string";
+		case "plan":
+			return Array.isArray(update.entries);
+		case "current_mode_update":
+			return typeof update.currentModeId === "string";
+		case "available_commands_update":
+			return Array.isArray(update.availableCommands);
+		case "config_option_update":
+			return Array.isArray(update.configOptions);
+		case "session_info_update":
+			return update.title === undefined || update.title === null || typeof update.title === "string";
+		case "usage_update":
+			return typeof update.size === "number" && typeof update.used === "number";
+		default:
+			return false;
+	}
+}
+
+/** Validator for new-session responses. */
+export const zNewSessionResponse = validator<NewSessionResponse>(
+	value => sessionResponse(value, true),
+	"new session response",
+);
+/** Validator for load-session responses. */
+export const zLoadSessionResponse = validator<LoadSessionResponse>(
+	value => sessionResponse(value, false),
+	"load session response",
+);
+/** Validator for fork-session responses. */
+export const zForkSessionResponse = validator<ForkSessionResponse>(
+	value => sessionResponse(value, true),
+	"fork session response",
+);
+/** Validator for prompt responses. */
+export const zPromptResponse = validator<PromptResponse>(value => {
+	if (typeof value !== "object" || value === null) return false;
+	const stopReason = (value as Record<string, unknown>).stopReason;
+	return (
+		stopReason === "end_turn" ||
+		stopReason === "max_tokens" ||
+		stopReason === "max_turn_requests" ||
+		stopReason === "refusal" ||
+		stopReason === "cancelled"
+	);
+}, "prompt response");
+/** Validator for session notifications. */
+export const zSessionNotification = validator<SessionNotification>(sessionNotification, "session notification");
+
+/** ACP runtime validators. */
+export const schema = {
+	zNewSessionResponse,
+	zLoadSessionResponse,
+	zForkSessionResponse,
+	zPromptResponse,
+	zSessionNotification,
+} as const;

package/src/acp/stream.ts

@@ -0,0 +1,82 @@
+import type { AnyMessage } from "./transport";
+
+/** 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 function ndJsonStream(output: WritableStream<Uint8Array>, input: ReadableStream<Uint8Array>): Stream {
+	const encoder = new TextEncoder();
+	const decoder = new TextDecoder();
+	const writable = new WritableStream<AnyMessage>({
+		async write(message) {
+			const writer = output.getWriter();
+			try {
+				await writer.write(encoder.encode(`${JSON.stringify(message)}\n`));
+			} finally {
+				writer.releaseLock();
+			}
+		},
+		async close() {
+			const writer = output.getWriter();
+			try {
+				await writer.close();
+			} finally {
+				writer.releaseLock();
+			}
+		},
+		async abort(reason) {
+			const writer = output.getWriter();
+			try {
+				await writer.abort(reason);
+			} finally {
+				writer.releaseLock();
+			}
+		},
+	});
+	let buffered = "";
+	const readable = new ReadableStream<AnyMessage>({
+		async start(controller) {
+			const reader = input.getReader();
+			try {
+				while (true) {
+					const next = await reader.read();
+					if (next.done) break;
+					buffered += decoder.decode(next.value, { stream: true });
+					let newline = buffered.indexOf("\n");
+					while (newline >= 0) {
+						const line = buffered.slice(0, newline).trimEnd();
+						buffered = buffered.slice(newline + 1);
+						if (line.length > 0) controller.enqueue(parseMessage(line));
+						newline = buffered.indexOf("\n");
+					}
+				}
+				buffered += decoder.decode();
+				const finalLine = buffered.trim();
+				if (finalLine.length > 0) controller.enqueue(parseMessage(finalLine));
+				controller.close();
+			} catch (error) {
+				controller.error(error);
+			} finally {
+				reader.releaseLock();
+			}
+		},
+	});
+	return { writable, readable };
+}
+
+function parseMessage(line: string): AnyMessage {
+	const value: unknown = JSON.parse(line);
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		Array.isArray(value) ||
+		!("jsonrpc" in value) ||
+		value.jsonrpc !== "2.0"
+	) {
+		throw new Error("Invalid JSON-RPC message");
+	}
+	return value as AnyMessage;
+}