@papert-code/sdk-typescript 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,839 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export interface Annotation {
+	type: string;
+	value: string;
+}
+export interface Usage {
+	input_tokens: number;
+	output_tokens: number;
+	cache_creation_input_tokens?: number;
+	cache_read_input_tokens?: number;
+	total_tokens?: number;
+}
+export interface ExtendedUsage extends Usage {
+	server_tool_use?: {
+		web_search_requests: number;
+	};
+	service_tier?: string;
+	cache_creation?: {
+		ephemeral_1h_input_tokens: number;
+		ephemeral_5m_input_tokens: number;
+	};
+}
+export interface ModelUsage {
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadInputTokens: number;
+	cacheCreationInputTokens: number;
+	webSearchRequests: number;
+	contextWindow: number;
+}
+export interface CLIPermissionDenial {
+	tool_name: string;
+	tool_use_id: string;
+	tool_input: unknown;
+}
+export interface TextBlock {
+	type: "text";
+	text: string;
+	annotations?: Annotation[];
+}
+export interface ThinkingBlock {
+	type: "thinking";
+	thinking: string;
+	signature?: string;
+	annotations?: Annotation[];
+}
+export interface ToolUseBlock {
+	type: "tool_use";
+	id: string;
+	name: string;
+	input: unknown;
+	annotations?: Annotation[];
+}
+export interface ToolResultBlock {
+	type: "tool_result";
+	tool_use_id: string;
+	content?: string | ContentBlock[];
+	is_error?: boolean;
+	annotations?: Annotation[];
+}
+export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock;
+export interface APIUserMessage {
+	role: "user";
+	content: string | ContentBlock[];
+}
+export interface APIAssistantMessage {
+	id: string;
+	type: "message";
+	role: "assistant";
+	model: string;
+	content: ContentBlock[];
+	stop_reason?: string | null;
+	usage: Usage;
+}
+export interface SDKUserMessage {
+	type: "user";
+	uuid?: string;
+	session_id: string;
+	message: APIUserMessage;
+	parent_tool_use_id: string | null;
+	options?: Record<string, unknown>;
+}
+export interface SDKAssistantMessage {
+	type: "assistant";
+	uuid: string;
+	session_id: string;
+	message: APIAssistantMessage;
+	parent_tool_use_id: string | null;
+}
+export interface SDKSystemMessage {
+	type: "system";
+	subtype: string;
+	uuid: string;
+	session_id: string;
+	data?: unknown;
+	cwd?: string;
+	tools?: string[];
+	mcp_servers?: Array<{
+		name: string;
+		status: string;
+	}>;
+	model?: string;
+	permission_mode?: string;
+	slash_commands?: string[];
+	papert_code_version?: string;
+	output_style?: string;
+	agents?: string[];
+	skills?: string[];
+	capabilities?: Record<string, unknown>;
+	compact_metadata?: {
+		trigger: "manual" | "auto";
+		pre_tokens: number;
+	};
+}
+export interface SDKResultMessageSuccess {
+	type: "result";
+	subtype: "success";
+	uuid: string;
+	session_id: string;
+	is_error: false;
+	duration_ms: number;
+	duration_api_ms: number;
+	num_turns: number;
+	result: string;
+	usage: ExtendedUsage;
+	modelUsage?: Record<string, ModelUsage>;
+	permission_denials: CLIPermissionDenial[];
+	[key: string]: unknown;
+}
+export interface SDKResultMessageError {
+	type: "result";
+	subtype: "error_max_turns" | "error_during_execution";
+	uuid: string;
+	session_id: string;
+	is_error: true;
+	duration_ms: number;
+	duration_api_ms: number;
+	num_turns: number;
+	usage: ExtendedUsage;
+	modelUsage?: Record<string, ModelUsage>;
+	permission_denials: CLIPermissionDenial[];
+	error?: {
+		type?: string;
+		message: string;
+		[key: string]: unknown;
+	};
+	[key: string]: unknown;
+}
+export type SDKResultMessage = SDKResultMessageSuccess | SDKResultMessageError;
+export interface MessageStartStreamEvent {
+	type: "message_start";
+	message: {
+		id: string;
+		role: "assistant";
+		model: string;
+	};
+}
+export interface ContentBlockStartEvent {
+	type: "content_block_start";
+	index: number;
+	content_block: ContentBlock;
+}
+export type ContentBlockDelta = {
+	type: "text_delta";
+	text: string;
+} | {
+	type: "thinking_delta";
+	thinking: string;
+} | {
+	type: "input_json_delta";
+	partial_json: string;
+};
+export interface ContentBlockDeltaEvent {
+	type: "content_block_delta";
+	index: number;
+	delta: ContentBlockDelta;
+}
+export interface ContentBlockStopEvent {
+	type: "content_block_stop";
+	index: number;
+}
+export interface MessageStopStreamEvent {
+	type: "message_stop";
+}
+export type StreamEvent = MessageStartStreamEvent | ContentBlockStartEvent | ContentBlockDeltaEvent | ContentBlockStopEvent | MessageStopStreamEvent;
+export interface SDKPartialAssistantMessage {
+	type: "stream_event";
+	uuid: string;
+	session_id: string;
+	event: StreamEvent;
+	parent_tool_use_id: string | null;
+}
+export type PermissionMode = "default" | "plan" | "auto-edit" | "yolo";
+/**
+ * TODO: Align with `ToolCallConfirmationDetails`
+ */
+export interface PermissionSuggestion {
+	type: "allow" | "deny" | "modify";
+	label: string;
+	description?: string;
+	modifiedInput?: unknown;
+}
+export interface HookRegistration {
+	event: string;
+	callback_id: string;
+}
+export interface CLIControlInterruptRequest {
+	subtype: "interrupt";
+}
+export interface CLIControlPermissionRequest {
+	subtype: "can_use_tool";
+	tool_name: string;
+	tool_use_id: string;
+	input: unknown;
+	permission_suggestions: PermissionSuggestion[] | null;
+	blocked_path: string | null;
+}
+declare enum AuthProviderType {
+	DYNAMIC_DISCOVERY = "dynamic_discovery",
+	GOOGLE_CREDENTIALS = "google_credentials",
+	SERVICE_ACCOUNT_IMPERSONATION = "service_account_impersonation"
+}
+export interface MCPServerConfig {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	url?: string;
+	httpUrl?: string;
+	headers?: Record<string, string>;
+	tcp?: string;
+	timeout?: number;
+	trust?: boolean;
+	description?: string;
+	includeTools?: string[];
+	excludeTools?: string[];
+	extensionName?: string;
+	oauth?: Record<string, unknown>;
+	authProviderType?: AuthProviderType;
+	targetAudience?: string;
+	targetServiceAccount?: string;
+}
+export interface CLIControlInitializeRequest {
+	subtype: "initialize";
+	hooks?: HookRegistration[] | null;
+	sdkMcpServers?: Record<string, MCPServerConfig>;
+	mcpServers?: Record<string, MCPServerConfig>;
+	agents?: SubagentConfig[];
+}
+export interface CLIControlSetPermissionModeRequest {
+	subtype: "set_permission_mode";
+	mode: PermissionMode;
+}
+export interface CLIHookCallbackRequest {
+	subtype: "hook_callback";
+	callback_id: string;
+	input: unknown;
+	tool_use_id: string | null;
+}
+export interface CLIControlMcpMessageRequest {
+	subtype: "mcp_message";
+	server_name: string;
+	message: {
+		jsonrpc?: string;
+		method: string;
+		params?: Record<string, unknown>;
+		id?: string | number | null;
+	};
+}
+export interface CLIControlSetModelRequest {
+	subtype: "set_model";
+	model: string;
+}
+export interface CLIControlMcpStatusRequest {
+	subtype: "mcp_server_status";
+}
+export interface CLIControlSupportedCommandsRequest {
+	subtype: "supported_commands";
+}
+export interface CLIControlSchedulerListRequest {
+	subtype: "scheduler_list";
+	cwd?: string;
+	include_disabled?: boolean;
+}
+export interface CLIControlSchedulerStatusRequest {
+	subtype: "scheduler_status";
+	cwd?: string;
+}
+export interface CLIControlSchedulerAddRequest {
+	subtype: "scheduler_add";
+	cwd?: string;
+	job: Record<string, unknown>;
+}
+export interface CLIControlSchedulerUpdateRequest {
+	subtype: "scheduler_update";
+	cwd?: string;
+	id: string;
+	patch: Record<string, unknown>;
+}
+export interface CLIControlSchedulerRemoveRequest {
+	subtype: "scheduler_remove";
+	cwd?: string;
+	id: string;
+}
+export interface CLIControlSchedulerRunRequest {
+	subtype: "scheduler_run";
+	cwd?: string;
+	id: string;
+	mode?: "due" | "force";
+}
+export interface CLIControlSchedulerRunsRequest {
+	subtype: "scheduler_runs";
+	cwd?: string;
+	id: string;
+	limit?: number;
+}
+export interface CLIControlSchedulerStartRequest {
+	subtype: "scheduler_start";
+	cwd?: string;
+	max_concurrent?: number;
+	queue_policy?: "queue" | "skip";
+}
+export interface CLIControlSchedulerStopRequest {
+	subtype: "scheduler_stop";
+	cwd?: string;
+}
+export type ControlRequestPayload = CLIControlInterruptRequest | CLIControlPermissionRequest | CLIControlInitializeRequest | CLIControlSetPermissionModeRequest | CLIHookCallbackRequest | CLIControlMcpMessageRequest | CLIControlSetModelRequest | CLIControlMcpStatusRequest | CLIControlSupportedCommandsRequest | CLIControlSchedulerListRequest | CLIControlSchedulerStatusRequest | CLIControlSchedulerAddRequest | CLIControlSchedulerUpdateRequest | CLIControlSchedulerRemoveRequest | CLIControlSchedulerRunRequest | CLIControlSchedulerRunsRequest | CLIControlSchedulerStartRequest | CLIControlSchedulerStopRequest;
+export interface CLIControlRequest {
+	type: "control_request";
+	request_id: string;
+	request: ControlRequestPayload;
+}
+export interface ControlResponse {
+	subtype: "success";
+	request_id: string;
+	response: unknown;
+}
+export interface ControlErrorResponse {
+	subtype: "error";
+	request_id: string;
+	error: string | {
+		message: string;
+		[key: string]: unknown;
+	};
+}
+export interface CLIControlResponse {
+	type: "control_response";
+	response: ControlResponse | ControlErrorResponse;
+}
+export interface ControlCancelRequest {
+	type: "control_cancel_request";
+	request_id?: string;
+}
+export type ControlMessage = CLIControlRequest | CLIControlResponse | ControlCancelRequest;
+/**
+ * Union of all SDK message types
+ */
+export type SDKMessage = SDKUserMessage | SDKAssistantMessage | SDKSystemMessage | SDKResultMessage | SDKPartialAssistantMessage;
+export declare function isSDKUserMessage(msg: any): msg is SDKUserMessage;
+export declare function isSDKAssistantMessage(msg: any): msg is SDKAssistantMessage;
+export declare function isSDKSystemMessage(msg: any): msg is SDKSystemMessage;
+export declare function isSDKResultMessage(msg: any): msg is SDKResultMessage;
+export declare function isSDKPartialAssistantMessage(msg: any): msg is SDKPartialAssistantMessage;
+export declare function isControlRequest(msg: any): msg is CLIControlRequest;
+export declare function isControlResponse(msg: any): msg is CLIControlResponse;
+export declare function isControlCancel(msg: any): msg is ControlCancelRequest;
+export type SubagentLevel = "session";
+export interface ModelConfig {
+	model?: string;
+	temp?: number;
+	top_p?: number;
+}
+export interface RunConfig {
+	max_time_minutes?: number;
+	max_turns?: number;
+}
+export interface SubagentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	systemPrompt: string;
+	level: SubagentLevel;
+	filePath?: string;
+	modelConfig?: Partial<ModelConfig>;
+	runConfig?: Partial<RunConfig>;
+	color?: string;
+	readonly isBuiltin?: boolean;
+}
+/**
+ * Transport interface for SDK-CLI communication
+ *
+ * The Transport abstraction enables communication between SDK and CLI via different mechanisms:
+ * - ProcessTransport: Local subprocess via stdin/stdout (initial implementation)
+ * - HttpTransport: Remote CLI via HTTP (future)
+ * - WebSocketTransport: Remote CLI via WebSocket (future)
+ */
+export interface Transport {
+	close(): Promise<void>;
+	waitForExit(): Promise<void>;
+	write(message: string): void;
+	readMessages(): AsyncGenerator<unknown, void, unknown>;
+	readonly isReady: boolean;
+	readonly exitError: Error | null;
+}
+export type ToolInput = Record<string, unknown>;
+export type CanUseTool = (toolName: string, input: ToolInput, options: {
+	signal: AbortSignal;
+	suggestions?: PermissionSuggestion[] | null;
+}) => Promise<PermissionResult>;
+export type PermissionResult = {
+	behavior: "allow";
+	updatedInput: ToolInput;
+} | {
+	behavior: "deny";
+	message: string;
+	interrupt?: boolean;
+};
+export interface ExternalMcpServerConfig {
+	command: string;
+	args?: string[];
+	env?: Record<string, string>;
+}
+export interface SdkMcpServerConfig {
+	connect: (transport: unknown) => Promise<void>;
+}
+/**
+ * Configuration options for creating a query session with the Papert CLI.
+ */
+export interface QueryOptions {
+	/**
+	 * The working directory for the query session.
+	 * This determines the context in which file operations and commands are executed.
+	 * @default process.cwd()
+	 */
+	cwd?: string;
+	/**
+	 * The AI model to use for the query session.
+	 * This takes precedence over the environment variables `OPENAI_MODEL` and `PAPERT_MODEL`
+	 * @example 'papert-max', 'papert-plus', 'papert-turbo'
+	 */
+	model?: string;
+	/**
+	 * Path to the Papert CLI executable or runtime specification.
+	 *
+	 * Supports multiple formats:
+	 * - 'papert' -> native binary (auto-detected from PATH)
+	 * - '/path/to/papert' -> native binary (explicit path)
+	 * - '/path/to/cli.js' -> Node.js bundle (default for .js files)
+	 * - '/path/to/index.ts' -> TypeScript source (requires tsx)
+	 * - 'bun:/path/to/cli.js' -> Force Bun runtime
+	 * - 'node:/path/to/cli.js' -> Force Node.js runtime
+	 * - 'tsx:/path/to/index.ts' -> Force tsx runtime
+	 * - 'deno:/path/to/cli.ts' -> Force Deno runtime
+	 *
+	 * If not provided, the SDK will auto-detect the CLI in this order:
+	 * 1. Bundled CLI inside the SDK package (dist/cli/cli.js)
+	 * 2. PAPERT_CODE_CLI_PATH environment variable
+	 * 3. ~/.volta/bin/papert
+	 * 4. ~/.npm-global/bin/papert
+	 * 5. /usr/local/bin/papert
+	 * 6. ~/.local/bin/papert
+	 * 7. ~/node_modules/.bin/papert
+	 * 8. ~/.yarn/bin/papert
+	 *
+	 * The .ts files are only supported for debugging purposes.
+	 *
+	 * @example 'papert'
+	 * @example '/usr/local/bin/papert'
+	 * @example 'tsx:/path/to/packages/cli/src/index.ts'
+	 */
+	pathToPapertExecutable?: string;
+	/**
+	 * Environment variables to pass to the Papert CLI process.
+	 * These variables will be merged with the current process environment.
+	 */
+	env?: Record<string, string>;
+	/**
+	 * Additional skills directories to load. The CLI will scan these paths for skills.
+	 * Accepts a single path or a list of paths.
+	 */
+	skillsPath?: string | string[];
+	/**
+	 * Permission mode controlling how the SDK handles tool execution approval.
+	 *
+	 * - 'default': Write tools are denied unless approved via `canUseTool` callback or in `allowedTools`.
+	 *   Read-only tools execute without confirmation.
+	 * - 'plan': Blocks all write tools, instructing AI to present a plan first.
+	 *   Read-only tools execute normally.
+	 * - 'auto-edit': Auto-approve edit tools (edit, write_file) while other tools require confirmation.
+	 * - 'yolo': All tools execute automatically without confirmation.
+	 *
+	 * **Priority Chain (highest to lowest):**
+	 * 1. `excludeTools` - Blocks tools completely (returns permission error)
+	 * 2. `permissionMode: 'plan'` - Blocks non-read-only tools (except exit_plan_mode)
+	 * 3. `permissionMode: 'yolo'` - Auto-approves all tools
+	 * 4. `allowedTools` - Auto-approves matching tools
+	 * 5. `canUseTool` callback - Custom approval logic
+	 * 6. Default behavior - Auto-deny in SDK mode
+	 *
+	 * @default 'default'
+	 * @see canUseTool For custom permission handling
+	 * @see allowedTools For auto-approving specific tools
+	 * @see excludeTools For blocking specific tools
+	 */
+	permissionMode?: "default" | "plan" | "auto-edit" | "yolo";
+	/**
+	 * Custom permission handler for tool execution approval.
+	 *
+	 * This callback is invoked when a tool requires confirmation and allows you to
+	 * programmatically approve or deny execution. It acts as a fallback after
+	 * `allowedTools` check but before default denial.
+	 *
+	 * **When is this called?**
+	 * - Only for tools requiring confirmation (write operations, shell commands, etc.)
+	 * - After `excludeTools` and `allowedTools` checks
+	 * - Not called in 'yolo' mode or 'plan' mode
+	 * - Not called for tools already in `allowedTools`
+	 *
+	 * **Usage with permissionMode:**
+	 * - 'default': Invoked for all write tools not in `allowedTools`; if not provided, auto-denied.
+	 * - 'auto-edit': Invoked for non-edit tools (edit/write_file auto-approved); if not provided, auto-denied.
+	 * - 'plan': Not invoked; write tools are blocked by plan mode.
+	 * - 'yolo': Not invoked; all tools auto-approved.
+	 *
+	 * @see allowedTools For auto-approving tools without callback
+	 */
+	canUseTool?: CanUseTool;
+	/**
+	 * External MCP (Model Context Protocol) servers to connect to.
+	 * Each server is identified by a unique name and configured with command, args, and environment.
+	 * @example { 'my-server': { command: 'node', args: ['server.js'], env: { PORT: '3000' } } }
+	 */
+	mcpServers?: Record<string, ExternalMcpServerConfig>;
+	/**
+	 * AbortController to cancel the query session.
+	 * Call abortController.abort() to terminate the session and cleanup resources.
+	 * Remember to handle the AbortError when the session is aborted.
+	 */
+	abortController?: AbortController;
+	/**
+	 * Enable debug mode for verbose logging.
+	 * When true, additional diagnostic information will be output.
+	 * Use this with `logLevel` to control the verbosity of the logs.
+	 * @default false
+	 */
+	debug?: boolean;
+	/**
+	 * Custom handler for stderr output from the Papert CLI process.
+	 * Use this to capture and process error messages or diagnostic output.
+	 */
+	stderr?: (message: string) => void;
+	/**
+	 * Logging level for the SDK.
+	 * Controls the verbosity of log messages output by the SDK.
+	 * @default 'info'
+	 */
+	logLevel?: "debug" | "info" | "warn" | "error";
+	/**
+	 * Maximum number of conversation turns before the session automatically terminates.
+	 * A turn consists of a user message and an assistant response.
+	 * @default -1 (unlimited)
+	 */
+	maxSessionTurns?: number;
+	/**
+	 * Equivalent to `tool.core` in settings.json.
+	 * List of core tools to enable for the session.
+	 * If specified, only these tools will be available to the AI.
+	 * @example ['read_file', 'write_file', 'run_terminal_cmd']
+	 */
+	coreTools?: string[];
+	/**
+	 * Equivalent to `tool.exclude` in settings.json.
+	 * List of tools to exclude from the session.
+	 *
+	 * **Behavior:**
+	 * - Excluded tools return a permission error immediately when invoked
+	 * - Takes highest priority - overrides all other permission settings
+	 * - Tools will not be available to the AI, even if in `coreTools` or `allowedTools`
+	 *
+	 * **Pattern matching:**
+	 * - Tool name: `'write_file'`, `'run_shell_command'`
+	 * - Tool class: `'WriteTool'`, `'ShellTool'`
+	 * - Shell command prefix: `'ShellTool(git commit)'` (matches commands starting with "git commit")
+	 *
+	 * @example ['run_terminal_cmd', 'delete_file', 'ShellTool(rm )']
+	 * @see allowedTools For allowing specific tools
+	 */
+	excludeTools?: string[];
+	/**
+	 * Equivalent to `tool.allowed` in settings.json.
+	 * List of tools that are allowed to run without confirmation.
+	 *
+	 * **Behavior:**
+	 * - Matching tools bypass `canUseTool` callback and execute automatically
+	 * - Only applies when tool requires confirmation (write operations, shell commands)
+	 * - Checked after `excludeTools` but before `canUseTool` callback
+	 * - Does not override `permissionMode: 'plan'` (plan mode blocks all write tools)
+	 * - Has no effect in `permissionMode: 'yolo'` (already auto-approved)
+	 *
+	 * **Pattern matching:**
+	 * - Tool name: `'write_file'`, `'run_shell_command'`
+	 * - Tool class: `'WriteTool'`, `'ShellTool'`
+	 * - Shell command prefix: `'ShellTool(git status)'` (matches commands starting with "git status")
+	 *
+	 * **Use cases:**
+	 * - Auto-approve safe shell commands: `['ShellTool(git status)', 'ShellTool(ls)']`
+	 * - Auto-approve specific tools: `['write_file', 'edit']`
+	 * - Combine with `permissionMode: 'default'` to selectively auto-approve tools
+	 *
+	 * @example ['read_file', 'ShellTool(git status)', 'ShellTool(npm test)']
+	 * @see canUseTool For custom approval logic
+	 * @see excludeTools For blocking specific tools
+	 */
+	allowedTools?: string[];
+	/**
+	 * Authentication type for the AI service.
+	 * - 'openai': Use OpenAI-compatible authentication
+	 * - 'papert-oauth': Use Papert OAuth authentication
+	 *
+	 * Though we support 'papert-oauth', it's not recommended to use it in the SDK.
+	 * Because the credentials are stored in `~/.papert` and may need to refresh periodically.
+	 */
+	authType?: "openai" | "papert-oauth";
+	/**
+	 * Configuration for subagents that can be invoked during the session.
+	 * Subagents are specialized AI agents that can handle specific tasks or domains.
+	 * The invocation is marked as a `task` tool use with the name of agent and a tool_use_id.
+	 * The tool use of these agent is marked with the parent_tool_use_id of the `task` tool use.
+	 */
+	agents?: SubagentConfig[];
+	/**
+	 * Include partial messages in the response stream.
+	 * When true, the SDK will emit incomplete messages as they are being generated,
+	 * allowing for real-time streaming of the AI's response.
+	 * @default false
+	 */
+	includePartialMessages?: boolean;
+}
+export declare class Query implements AsyncIterable<SDKMessage> {
+	private transport;
+	private options;
+	private sessionId;
+	private inputStream;
+	private sdkMessages;
+	private abortController;
+	private pendingControlRequests;
+	private sdkMcpTransports;
+	readonly initialized: Promise<void>;
+	private closed;
+	private messageRouterStarted;
+	private firstResultReceivedPromise?;
+	private firstResultReceivedResolve?;
+	private readonly isSingleTurn;
+	constructor(transport: Transport, options: QueryOptions, singleTurn?: boolean);
+	private initialize;
+	private startMessageRouter;
+	private routeMessage;
+	private handleControlRequest;
+	private handlePermissionRequest;
+	private handleMcpMessage;
+	private handleMcpRequest;
+	private handleControlResponse;
+	private handleControlCancelRequest;
+	private sendControlRequest;
+	private sendControlResponse;
+	close(): Promise<void>;
+	private readSdkMessages;
+	next(...args: [
+	] | [
+		unknown
+	]): Promise<IteratorResult<SDKMessage>>;
+	return(value?: unknown): Promise<IteratorResult<SDKMessage>>;
+	throw(e?: unknown): Promise<IteratorResult<SDKMessage>>;
+	[Symbol.asyncIterator](): AsyncIterator<SDKMessage>;
+	streamInput(messages: AsyncIterable<SDKUserMessage>): Promise<void>;
+	endInput(): void;
+	interrupt(): Promise<void>;
+	setPermissionMode(mode: string): Promise<void>;
+	setModel(model: string): Promise<void>;
+	/**
+	 * Get list of control commands supported by the CLI
+	 *
+	 * @returns Promise resolving to list of supported command names
+	 * @throws Error if query is closed
+	 */
+	supportedCommands(): Promise<Record<string, unknown> | null>;
+	/**
+	 * Get the status of MCP servers
+	 *
+	 * @returns Promise resolving to MCP server status information
+	 * @throws Error if query is closed
+	 */
+	mcpServerStatus(): Promise<Record<string, unknown> | null>;
+	getSessionId(): string;
+	isClosed(): boolean;
+}
+export declare function query({ prompt, options, }: {
+	/**
+	 * The prompt to send to the Papert Code CLI process.
+	 * - `string` for single-turn query,
+	 * - `AsyncIterable<SDKUserMessage>` for multi-turn query.
+	 *
+	 * The transport will remain open until the prompt is done.
+	 */
+	prompt: string | AsyncIterable<SDKUserMessage>;
+	/**
+	 * Configuration options for the query.
+	 */
+	options?: QueryOptions;
+}): Query;
+export declare class AbortError extends Error {
+	constructor(message?: string);
+}
+export declare function isAbortError(error: unknown): error is AbortError;
+export interface CreateSessionOptions {
+	sessionId?: string;
+	options?: QueryOptions;
+}
+export declare class PapertClient {
+	private readonly options;
+	private readonly sessions;
+	constructor(options?: QueryOptions);
+	createSession({ sessionId, options, }?: CreateSessionOptions): PapertClientSession;
+	getSession(sessionId: string): PapertClientSession | undefined;
+	getDefaultOptions(): QueryOptions;
+	unregisterSession(sessionId: string): void;
+	close(): Promise<void>;
+}
+export declare class PapertClientSession {
+	private readonly sessionId;
+	private readonly client;
+	private readonly options;
+	private readonly activeQueries;
+	private closed;
+	constructor(sessionId: string, client: PapertClient, options?: QueryOptions);
+	getSessionId(): string;
+	isClosed(): boolean;
+	stream(prompt: string, options?: QueryOptions): Query;
+	send(prompt: string, options?: QueryOptions): Promise<SDKMessage[]>;
+	close(): Promise<void>;
+	private createPromptStream;
+}
+export declare function createClient(options?: QueryOptions): PapertClient;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LoggerConfig {
+	debug?: boolean;
+	stderr?: (message: string) => void;
+	logLevel?: LogLevel;
+}
+export interface ScopedLogger {
+	debug(message: string, ...args: unknown[]): void;
+	info(message: string, ...args: unknown[]): void;
+	warn(message: string, ...args: unknown[]): void;
+	error(message: string, ...args: unknown[]): void;
+}
+export declare class SdkLogger {
+	private static config;
+	private static effectiveLevel;
+	static configure(config: LoggerConfig): void;
+	private static determineLogLevel;
+	private static isValidLogLevel;
+	private static shouldLog;
+	private static formatTimestamp;
+	private static formatMessage;
+	private static log;
+	static createLogger(scope: string): ScopedLogger;
+	static getEffectiveLevel(): LogLevel;
+}
+export type ApprovalMode = "default" | "yolo" | "auto-edit";
+export interface PapertAgentOptions {
+	/**
+	 * Path to the papert-code CLI entrypoint. Defaults to the package entry
+	 * resolved from Node (equivalent to `require.resolve('@papert-code/papert-code')`).
+	 */
+	cliBinaryPath?: string;
+	/**
+	 * CLI arguments to seed the agent with (mirrors CLI flags).
+	 */
+	cliArgs?: {
+		model?: string;
+		approvalMode?: ApprovalMode;
+		baseUrl?: string;
+		apiKey?: string;
+		cwd?: string;
+		extraArgs?: string[];
+	};
+}
+export interface RunPromptOptions {
+	/**
+	 * Additional CLI flags to append just for this prompt.
+	 */
+	extraArgs?: string[];
+	/**
+	 * AbortSignal to terminate the underlying process.
+	 */
+	signal?: AbortSignal;
+}
+export interface PapertAgent {
+	runPrompt: (prompt: string, options?: RunPromptOptions) => Promise<{
+		stdout: string;
+		stderr: string;
+		exitCode: number | null;
+	}>;
+}
+/**
+ * Lightweight programmatic wrapper around the papert-code CLI.
+ *
+ * Example:
+ * const agent = await createPapertAgent({
+ *   cliArgs: { model: 'gemini-3-pro', approvalMode: 'auto_edit' },
+ * });
+ * const result = await agent.runPrompt('Summarize outstanding TODOs');
+ */
+export declare function createPapertAgent(options?: PapertAgentOptions): Promise<PapertAgent>;
+export type HttpSseTransportOptions = {
+	baseUrl: string;
+	/** Token required to create a session (server token). */
+	serverToken: string;
+	/** Optional override; defaults to process.cwd() on the server. */
+	workspaceRoot?: string;
+};
+export declare class HttpSseTransport implements Transport {
+	private readonly options;
+	private _exitError;
+	private _isReady;
+	private session;
+	private pendingWrites;
+	constructor(options: HttpSseTransportOptions);
+	get isReady(): boolean;
+	get exitError(): Error | null;
+	close(): Promise<void>;
+	waitForExit(): Promise<void>;
+	write(message: string): void;
+	readMessages(): AsyncGenerator<unknown, void, unknown>;
+	private createSession;
+}
+
+export {};