@robota-sdk/agent-sdk 3.0.0-beta.43 → 3.0.0-beta.44

package/dist/node/index.d.ts

@@ -1,9 +1,9 @@
-import { IHookTypeExecutor, IHookDefinition, IHookInput, IHookResult, THooksConfig, TTrustLevel, TPermissionMode, IAIProvider, TToolArgs, IToolWithEventService, TUniversalMessage, IContextWindowState } from '@robota-sdk/agent-core';
-export { IContextTokenUsage, IContextWindowState, IHookInput, IPermissionLists, THookEvent, THooksConfig, TPermissionDecision, TPermissionMode, TRUST_TO_MODE, TToolArgs, TTrustLevel, evaluatePermission, runHooks } from '@robota-sdk/agent-core';
+import { IHookTypeExecutor, IHookDefinition, IHookInput, IHookResult, THooksConfig, TTrustLevel, TPermissionMode, IAIProvider, TToolArgs, IToolWithEventService, IHistoryEntry, IContextWindowState, TUniversalMessage } from '@robota-sdk/agent-core';
+export { IAIProvider, IContextTokenUsage, IContextWindowState, IHistoryEntry, IHookInput, IPermissionLists, THookEvent, THooksConfig, TPermissionDecision, TPermissionMode, TRUST_TO_MODE, TToolArgs, TTrustLevel, chatEntryToMessage, evaluatePermission, getMessagesForAPI, isChatEntry, messageToHistoryEntry, runHooks } from '@robota-sdk/agent-core';
+import { ITerminalOutput, SessionStore, TPermissionHandler, ISessionLogger, Session, FileSessionLogger } from '@robota-sdk/agent-sessions';
+export { ISpinner, ITerminalOutput } from '@robota-sdk/agent-sessions';
 import { createZodFunctionTool } from '@robota-sdk/agent-tools';
-export { TToolResult, bashTool, editTool, globTool, grepTool, readTool, writeTool } from '@robota-sdk/agent-tools';
-import { ITerminalOutput, SessionStore, TPermissionHandler, ISessionLogger, Session, FileSessionLogger, TPermissionResult } from '@robota-sdk/agent-sessions';
-export { FileSessionLogger, ISessionLogger, ISessionOptions, ISessionRecord, ISpinner, ITerminalOutput, Session, SessionStore, SilentSessionLogger, TPermissionHandler, TPermissionResult, TSessionLogData } from '@robota-sdk/agent-sessions';
+export { TToolResult } from '@robota-sdk/agent-tools';
 
 /**
  * Prompt hook executor — evaluates a prompt via an AI model.
@@ -112,13 +112,6 @@ interface ILoadedContext {
     /** Extracted "Compact Instructions" section from CLAUDE.md, if present */
     compactInstructions?: string;
 }
-/**
- * Load all AGENTS.md and CLAUDE.md files found by walking up from `cwd`.
- * Files from higher directories appear before files from lower directories.
- *
- * @param cwd - Starting directory for the walk-up search
- */
-declare function loadContext(cwd: string): Promise<ILoadedContext>;
 
 type TProjectType = 'node' | 'python' | 'rust' | 'go' | 'unknown';
 type TPackageManager = 'pnpm' | 'yarn' | 'npm' | 'bun';
@@ -129,10 +122,6 @@ interface IProjectInfo {
     packageManager?: TPackageManager;
     language: TLanguage;
 }
-/**
- * Detect the project type, language, name, and package manager from `cwd`.
- */
-declare function detectProject(cwd: string): Promise<IProjectInfo>;
 
 /**
  * System prompt builder — assembles the system message sent to the AI model
@@ -162,7 +151,6 @@ interface ISystemPromptParams {
         disableModelInvocation?: boolean;
     }>;
 }
-declare function buildSystemPrompt(params: ISystemPromptParams): string;
 
 /**
  * Session factory — assembles a fully-configured Session from config, context,
@@ -223,35 +211,6 @@ interface ICreateSessionOptions {
     /** Additional hook type executors beyond the defaults (prompt, agent). */
     additionalHookExecutors?: IHookTypeExecutor[];
 }
-/**
- * Create a fully-configured Session instance.
- *
- * Assembles provider, tools, and system prompt, then passes them
- * to Session as pre-constructed dependencies.
- */
-declare function createSession(options: ICreateSessionOptions): Session;
-
-/**
- * Default tool set factory — creates the standard set of CLI tools.
- */
-
-/** Human-readable descriptions of the built-in tools (for system prompt) */
-declare const DEFAULT_TOOL_DESCRIPTIONS: string[];
-/**
- * Create the default set of CLI tools.
- * Returns the 8 standard tools as IToolWithEventService[].
- */
-declare function createDefaultTools(): IToolWithEventService[];
-
-/**
- * Provider factory — creates an AI provider from resolved config.
- */
-
-/**
- * Create an AI provider from the resolved config.
- * Currently supports Anthropic only. Throws if no API key is available.
- */
-declare function createProvider(config: IResolvedConfig): IAIProvider;
 
 /**
  * Framework system prompt suffixes for subagent sessions.
@@ -331,6 +290,8 @@ interface ISubagentOptions {
     parentContext: ILoadedContext;
     /** Parent session's available tools (to inherit/filter). */
     parentTools: IToolWithEventService[];
+    /** AI provider instance. */
+    provider: IAIProvider;
     /** Terminal output interface. */
     terminal: ITerminalOutput;
     /** Whether this is a fork worker (uses fork suffix instead of standard). */
@@ -394,63 +355,260 @@ declare function createSubagentLogger(parentSessionId: string, _agentId: string,
 declare function resolveSubagentLogDir(parentSessionId: string, baseLogsDir: string): string;
 
 /**
- * query() — single entry point for running an AI agent conversation.
- * Automatically loads config, context, and project info.
+ * Types for InteractiveSession — event-driven session wrapper.
  */
 
-interface IQueryOptions {
-    cwd?: string;
-    permissionMode?: TPermissionMode;
-    maxTurns?: number;
-    provider?: IAIProvider;
-    permissionHandler?: (toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
-    onTextDelta?: (delta: string) => void;
-    /** Callback when context is compacted */
-    onCompact?: (summary: string) => void;
+/** Permission handler result — SDK-owned type (mirrors agent-sessions TPermissionResult).
+ *  true = allow, false = deny, 'allow-session' = allow and remember for this session. */
+type TPermissionResultValue = boolean | 'allow-session';
+/** Tool execution state visible to clients. */
+interface IToolState {
+    toolName: string;
+    firstArg: string;
+    isRunning: boolean;
+    result?: 'success' | 'error' | 'denied';
+    diffLines?: IDiffLine[];
+    diffFile?: string;
 }
-/**
- * query() — single entry point for running an AI agent conversation.
- * Equivalent to Claude Agent SDK's query() function.
- * Automatically loads config, context, and project info.
- */
-declare function query(prompt: string, options?: IQueryOptions): Promise<string>;
+/** A single diff line for Edit tool display. */
+interface IDiffLine {
+    type: 'add' | 'remove' | 'context';
+    text: string;
+    lineNumber: number;
+}
+/** Result of a completed prompt execution. */
+interface IExecutionResult {
+    response: string;
+    history: IHistoryEntry[];
+    toolSummaries: IToolSummary[];
+    contextState: IContextWindowState;
+}
+/** Summary of a tool call extracted from history. */
+interface IToolSummary {
+    name: string;
+    args: string;
+}
+/** Permission handler delegate — clients provide their own UI. */
+type TInteractivePermissionHandler = (toolName: string, toolArgs: TToolArgs) => Promise<TPermissionResultValue>;
+/** Events emitted by InteractiveSession. */
+interface IInteractiveSessionEvents {
+    text_delta: (delta: string) => void;
+    tool_start: (state: IToolState) => void;
+    tool_end: (state: IToolState) => void;
+    thinking: (isThinking: boolean) => void;
+    complete: (result: IExecutionResult) => void;
+    error: (error: Error) => void;
+    context_update: (state: IContextWindowState) => void;
+    interrupted: (result: IExecutionResult) => void;
+}
+type TInteractiveEventName = keyof IInteractiveSessionEvents;
 
 /**
- * Load and merge all settings files, validate with Zod, return resolved config.
+ * InteractiveSession — the single entry point for all SDK consumers.
  *
- * @param cwd - The working directory (project root) to search for settings
+ * Wraps Session (composition). Manages streaming text accumulation,
+ * tool execution state tracking, prompt queuing, abort orchestration,
+ * message history, and system command execution.
+ *
+ * Config/context loading is internal. Consumer provides cwd + provider.
  */
-declare function loadConfig(cwd: string): Promise<IResolvedConfig>;
 
-/**
- * Interactive permission prompt — asks the user whether to allow a tool invocation
- * using an arrow-key selector. Canonical implementation (SSOT).
- * Used by both agent-sdk query() and agent-cli.
- */
+/** Standard construction: cwd + provider. Config/context loaded internally. */
+interface IInteractiveSessionStandardOptions {
+    cwd: string;
+    provider: IAIProvider;
+    permissionMode?: ICreateSessionOptions['permissionMode'];
+    maxTurns?: number;
+    permissionHandler?: TInteractivePermissionHandler;
+}
+/** Test/advanced construction: inject pre-built session directly. */
+interface IInteractiveSessionInjectedOptions {
+    session: Session;
+    cwd?: string;
+    provider?: IAIProvider;
+    permissionMode?: ICreateSessionOptions['permissionMode'];
+    maxTurns?: number;
+    permissionHandler?: TInteractivePermissionHandler;
+}
+type IInteractiveSessionOptions = IInteractiveSessionStandardOptions | IInteractiveSessionInjectedOptions;
+declare class InteractiveSession {
+    private session;
+    private readonly commandExecutor;
+    private readonly listeners;
+    private initialized;
+    private initPromise;
+    private streamingText;
+    private flushTimer;
+    private activeTools;
+    private executing;
+    private pendingPrompt;
+    private pendingDisplayInput;
+    private pendingRawInput;
+    private history;
+    constructor(options: IInteractiveSessionOptions);
+    private initializeAsync;
+    private ensureInitialized;
+    private getSessionOrThrow;
+    on<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+    off<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+    private emit;
+    /** Submit a prompt. Queues if already executing (max 1 queued). */
+    submit(input: string, displayInput?: string, rawInput?: string): Promise<void>;
+    /** Execute a system command by name. Returns null if not found. */
+    executeCommand(name: string, args: string): Promise<{
+        message: string;
+        success: boolean;
+        data?: Record<string, unknown>;
+    } | null>;
+    /** Abort current execution and clear queue. */
+    abort(): void;
+    /** Cancel queued prompt without aborting current execution. */
+    cancelQueue(): void;
+    isExecuting(): boolean;
+    getPendingPrompt(): string | null;
+    /** Get full history timeline (chat + events) for TUI rendering */
+    getFullHistory(): IHistoryEntry[];
+    /** Get chat messages only (backward compatible) */
+    getMessages(): TUniversalMessage[];
+    getStreamingText(): string;
+    getActiveTools(): IToolState[];
+    getContextState(): IContextWindowState;
+    /** Access underlying Session. For advanced use / testing only. */
+    getSession(): Session;
+    private executePrompt;
+    private handleTextDelta;
+    private handleToolExecution;
+    /** Push tool execution summary into messages (before Robota response).
+     *  Moves tool info from activeTools (real-time display) to messages (permanent display).
+     *  After this, activeTools will be cleared by clearStreaming(). */
+    private pushToolSummaryMessage;
+    private clearStreaming;
+    private flushStreaming;
+    private buildResult;
+    private buildInterruptedResult;
+    private extractToolSummaries;
+    private trimCompletedTools;
+}
 
 /**
- * Prompt the user for approval before running a tool.
+ * createQuery() — factory that returns a prompt-only convenience function.
+ *
+ * Usage:
+ *   const query = createQuery({ provider });
+ *   const answer = await query('What files are here?');
  */
-declare function promptForApproval(terminal: ITerminalOutput, toolName: string, toolArgs: TToolArgs): Promise<boolean>;
 
+interface ICreateQueryOptions {
+    /** AI provider instance (required). */
+    provider: IAIProvider;
+    /** Working directory. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Permission mode. Defaults to 'bypassPermissions' for programmatic use. */
+    permissionMode?: TPermissionMode;
+    /** Maximum agentic turns per query. */
+    maxTurns?: number;
+    /** Permission handler callback. */
+    permissionHandler?: TInteractivePermissionHandler;
+    /** Streaming text callback. */
+    onTextDelta?: (delta: string) => void;
+}
 /**
- * Standard Robota storage paths.
+ * Create a prompt-only query function bound to a provider.
  *
- * All CLI runtime data lives under .robota/ (project) or ~/.robota/ (user).
- * .agents/ is read-only from CLI's perspective (owned by AGENTS.md standard).
+ * ```typescript
+ * import { createQuery } from '@robota-sdk/agent-sdk';
+ * import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
+ *
+ * const query = createQuery({ provider: new AnthropicProvider({ apiKey: '...' }) });
+ * const answer = await query('List all TypeScript files');
+ * ```
  */
-/** Project-level .robota/ paths (relative to cwd). */
-declare function projectPaths(cwd: string): {
-    settings: string;
-    settingsLocal: string;
-    logs: string;
-    sessions: string;
-};
-/** User-level ~/.robota/ paths. */
-declare function userPaths(): {
-    settings: string;
-    sessions: string;
-};
+declare function createQuery(options: ICreateQueryOptions): (prompt: string) => Promise<string>;
+
+/** A command entry */
+interface ICommand {
+    /** Command name without slash (e.g., "mode") */
+    name: string;
+    /** Short description shown in autocomplete */
+    description: string;
+    /** Source identifier (e.g., "builtin", "skill") */
+    source: string;
+    /** Subcommands for hierarchical menus */
+    subcommands?: ICommand[];
+    /** Execute the command. Args is everything after the command name. */
+    execute?: (args: string) => void | Promise<void>;
+    /** Full SKILL.md content (only for skill commands) */
+    skillContent?: string;
+    /** Hint for the expected argument (Claude Code frontmatter) */
+    argumentHint?: string;
+    /** When true, models cannot invoke this skill autonomously */
+    disableModelInvocation?: boolean;
+    /** When false, users cannot invoke this skill directly */
+    userInvocable?: boolean;
+    /** List of tools this skill is allowed to use */
+    allowedTools?: string[];
+    /** Preferred model for executing this skill */
+    model?: string;
+    /** Effort level hint for the skill */
+    effort?: string;
+    /** Context scope for the skill (e.g., "project") */
+    context?: string;
+    /** Agent identity to use when executing this skill */
+    agent?: string;
+    /** Plugin installation directory (plugin skills/commands only) */
+    pluginDir?: string;
+}
+/** A source that provides commands */
+interface ICommandSource {
+    name: string;
+    getCommands(): ICommand[];
+}
+
+/** Aggregates commands from multiple sources */
+declare class CommandRegistry {
+    private sources;
+    addSource(source: ICommandSource): void;
+    /** Get all commands, optionally filtered by prefix */
+    getCommands(filter?: string): ICommand[];
+    /** Resolve a short name to its fully qualified plugin:name form */
+    resolveQualifiedName(shortName: string): string | null;
+    /** Get subcommands for a specific command */
+    getSubcommands(commandName: string): ICommand[];
+}
+
+/** Command source for built-in commands */
+declare class BuiltinCommandSource implements ICommandSource {
+    readonly name = "builtin";
+    private readonly commands;
+    constructor();
+    getCommands(): ICommand[];
+}
+
+interface IFrontmatter {
+    name?: string;
+    description?: string;
+    argumentHint?: string;
+    disableModelInvocation?: boolean;
+    userInvocable?: boolean;
+    allowedTools?: string[];
+    model?: string;
+    effort?: string;
+    context?: string;
+    agent?: string;
+}
+/** Parse YAML-like frontmatter between --- markers */
+declare function parseFrontmatter(content: string): IFrontmatter | null;
+/** Command source that discovers skills from multiple directories */
+declare class SkillCommandSource implements ICommandSource {
+    readonly name = "skill";
+    private readonly cwd;
+    private readonly home;
+    private cachedCommands;
+    constructor(cwd: string, home?: string);
+    getCommands(): ICommand[];
+    getModelInvocableSkills(): ICommand[];
+    getUserInvocableSkills(): ICommand[];
+}
 
 /**
  * PluginSettingsStore — single point of read/write for plugin-related settings.
@@ -814,6 +972,75 @@ declare class BundlePluginInstaller {
     private defaultExec;
 }
 
+/**
+ * Command source that discovers skills and commands from loaded BundlePlugins.
+ *
+ * - Skills: exposed as `/name` with `(plugin-name)` hint in description.
+ * - Commands: exposed as `/plugin:command` (already namespaced by the loader).
+ */
+declare class PluginCommandSource implements ICommandSource {
+    readonly name = "plugin";
+    private readonly plugins;
+    constructor(plugins: ILoadedBundlePlugin[]);
+    getCommands(): ICommand[];
+}
+
+/**
+ * System commands — SDK-level command execution logic.
+ *
+ * Pure functions that operate on InteractiveSession.
+ * No React, no TUI, no framework dependencies.
+ * CLI wraps these as slash commands with UI chrome.
+ */
+
+/** Result of a system command execution. */
+interface ICommandResult {
+    /** Human-readable output message */
+    message: string;
+    /** Command completed successfully */
+    success: boolean;
+    /** Additional structured data (command-specific) */
+    data?: Record<string, unknown>;
+}
+/** A system command with name, description, and execute logic. */
+interface ISystemCommand {
+    name: string;
+    description: string;
+    execute(session: InteractiveSession, args: string): Promise<ICommandResult> | ICommandResult;
+}
+
+/**
+ * Build a skill prompt from slash command input.
+ * Supports variable substitution and shell command preprocessing.
+ */
+
+/** Context variables available during skill prompt processing */
+interface SkillPromptContext {
+    /** Current session ID — substituted for ${CLAUDE_SESSION_ID} */
+    sessionId?: string;
+    /** Directory containing SKILL.md — substituted for ${CLAUDE_SKILL_DIR} */
+    skillDir?: string;
+}
+/**
+ * Substitute variables in skill content.
+ *
+ * Supported variables:
+ * - `$ARGUMENTS` — all arguments passed to the skill
+ * - `$ARGUMENTS[N]` — argument by index (0-based)
+ * - `$N` — shorthand for `$ARGUMENTS[N]` (single digit, 0-9)
+ * - `${CLAUDE_SESSION_ID}` — current session ID
+ * - `${CLAUDE_SKILL_DIR}` — directory containing SKILL.md
+ */
+declare function substituteVariables(content: string, args: string, context?: SkillPromptContext): string;
+/**
+ * Preprocess shell commands in skill content.
+ * Matches `` !`...` `` patterns and replaces them with command output.
+ * Commands have a 5-second timeout.
+ */
+declare function preprocessShellCommands(content: string): Promise<string>;
+/** Build a skill prompt from a slash command input and registry */
+declare function buildSkillPrompt(input: string, registry: CommandRegistry, context?: SkillPromptContext): Promise<string | null>;
+
 /**
  * All built-in agent definitions shipped with the SDK.
  * Order matters: general-purpose is the default fallback.
@@ -843,6 +1070,8 @@ interface IAgentToolDeps {
     context: ILoadedContext;
     tools: IToolWithEventService[];
     terminal: ITerminalOutput;
+    /** AI provider instance (passed from consumer). */
+    provider: IAIProvider;
     /** Permission mode from parent session (bypassPermissions, acceptEdits, etc.). */
     permissionMode?: TPermissionMode;
     permissionHandler?: TPermissionHandler;
@@ -871,238 +1100,34 @@ declare function retrieveAgentToolDeps(key: object): IAgentToolDeps | undefined;
  */
 declare function createAgentTool(deps: IAgentToolDeps): ReturnType<typeof createZodFunctionTool>;
 
-/** A slash command entry */
-interface ISlashCommand {
-    /** Command name without slash (e.g., "mode") */
-    name: string;
-    /** Short description shown in autocomplete */
-    description: string;
-    /** Source identifier (e.g., "builtin", "skill") */
-    source: string;
-    /** Subcommands for hierarchical menus */
-    subcommands?: ISlashCommand[];
-    /** Execute the command. Args is everything after the command name. */
-    execute?: (args: string) => void | Promise<void>;
-    /** Full SKILL.md content (only for skill commands) */
-    skillContent?: string;
-    /** Hint for the expected argument (Claude Code frontmatter) */
-    argumentHint?: string;
-    /** When true, models cannot invoke this skill autonomously */
-    disableModelInvocation?: boolean;
-    /** When false, users cannot invoke this skill directly */
-    userInvocable?: boolean;
-    /** List of tools this skill is allowed to use */
-    allowedTools?: string[];
-    /** Preferred model for executing this skill */
-    model?: string;
-    /** Effort level hint for the skill */
-    effort?: string;
-    /** Context scope for the skill (e.g., "project") */
-    context?: string;
-    /** Agent identity to use when executing this skill */
-    agent?: string;
-    /** Plugin installation directory (plugin skills/commands only) */
-    pluginDir?: string;
-}
-/** A source that provides slash commands */
-interface ICommandSource {
-    name: string;
-    getCommands(): ISlashCommand[];
-}
-
-/** Aggregates commands from multiple sources */
-declare class CommandRegistry {
-    private sources;
-    addSource(source: ICommandSource): void;
-    /** Get all commands, optionally filtered by prefix */
-    getCommands(filter?: string): ISlashCommand[];
-    /** Resolve a short name to its fully qualified plugin:name form */
-    resolveQualifiedName(shortName: string): string | null;
-    /** Get subcommands for a specific command */
-    getSubcommands(commandName: string): ISlashCommand[];
-}
-
-/** Command source for built-in commands */
-declare class BuiltinCommandSource implements ICommandSource {
-    readonly name = "builtin";
-    private readonly commands;
-    constructor();
-    getCommands(): ISlashCommand[];
-}
-
-interface IFrontmatter {
-    name?: string;
-    description?: string;
-    argumentHint?: string;
-    disableModelInvocation?: boolean;
-    userInvocable?: boolean;
-    allowedTools?: string[];
-    model?: string;
-    effort?: string;
-    context?: string;
-    agent?: string;
-}
-/** Parse YAML-like frontmatter between --- markers */
-declare function parseFrontmatter(content: string): IFrontmatter | null;
-/** Command source that discovers skills from multiple directories */
-declare class SkillCommandSource implements ICommandSource {
-    readonly name = "skill";
-    private readonly cwd;
-    private readonly home;
-    private cachedCommands;
-    constructor(cwd: string, home?: string);
-    getCommands(): ISlashCommand[];
-    getModelInvocableSkills(): ISlashCommand[];
-    getUserInvocableSkills(): ISlashCommand[];
-}
-
 /**
- * Types for InteractiveSession — event-driven session wrapper.
+ * Standard Robota storage paths.
+ *
+ * All CLI runtime data lives under .robota/ (project) or ~/.robota/ (user).
+ * .agents/ is read-only from CLI's perspective (owned by AGENTS.md standard).
  */
-
-/** Tool execution state visible to clients. */
-interface IToolState {
-    toolName: string;
-    firstArg: string;
-    isRunning: boolean;
-    result?: 'success' | 'error' | 'denied';
-    diffLines?: IDiffLine[];
-    diffFile?: string;
-}
-/** A single diff line for Edit tool display. */
-interface IDiffLine {
-    type: 'add' | 'remove' | 'context';
-    content: string;
-    lineNumber?: number;
-}
-/** Result of a completed prompt execution. */
-interface IExecutionResult {
-    response: string;
-    messages: TUniversalMessage[];
-    toolSummaries: IToolSummary[];
-    contextState: IContextWindowState;
-}
-/** Summary of a tool call extracted from history. */
-interface IToolSummary {
-    name: string;
-    args: string;
-}
-/** Permission handler delegate — clients provide their own UI. */
-type TInteractivePermissionHandler = (toolName: string, toolArgs: TToolArgs) => Promise<TPermissionResult>;
-/** Events emitted by InteractiveSession. */
-interface IInteractiveSessionEvents {
-    text_delta: (delta: string) => void;
-    tool_start: (state: IToolState) => void;
-    tool_end: (state: IToolState) => void;
-    thinking: (isThinking: boolean) => void;
-    complete: (result: IExecutionResult) => void;
-    error: (error: Error) => void;
-    context_update: (state: IContextWindowState) => void;
-    interrupted: (result: IExecutionResult) => void;
-}
-type TInteractiveEventName = keyof IInteractiveSessionEvents;
+/** Project-level .robota/ paths (relative to cwd). */
+declare function projectPaths(cwd: string): {
+    settings: string;
+    settingsLocal: string;
+    logs: string;
+    sessions: string;
+};
+/** User-level ~/.robota/ paths. */
+declare function userPaths(): {
+    settings: string;
+    sessions: string;
+};
 
 /**
- * InteractiveSession — event-driven session wrapper for any client.
- *
- * Wraps Session (composition) to provide streaming text accumulation,
- * tool execution state tracking, prompt queuing, abort orchestration,
- * and message history management. Previously embedded in CLI React hooks.
- *
- * Clients (CLI, web, API server, Dynamic Worker) subscribe to events
- * and call submit/abort/cancelQueue.
+ * Interactive permission prompt — asks the user whether to allow a tool invocation
+ * using an arrow-key selector. Canonical implementation (SSOT).
+ * Used by both agent-sdk query() and agent-cli.
  */
 
-interface IInteractiveSessionOptions {
-    config: ICreateSessionOptions['config'];
-    context: ICreateSessionOptions['context'];
-    projectInfo?: ICreateSessionOptions['projectInfo'];
-    sessionStore?: ICreateSessionOptions['sessionStore'];
-    permissionMode?: ICreateSessionOptions['permissionMode'];
-    maxTurns?: number;
-    cwd?: string;
-    permissionHandler?: TInteractivePermissionHandler;
-    /** Optional: inject pre-built session (for testing). */
-    session?: Session;
-}
-declare class InteractiveSession {
-    private readonly session;
-    private readonly listeners;
-    private streamingText;
-    private flushTimer;
-    private activeTools;
-    private executing;
-    private pendingPrompt;
-    private pendingDisplayInput;
-    private pendingRawInput;
-    private messages;
-    constructor(options: IInteractiveSessionOptions);
-    on<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
-    off<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
-    private emit;
-    /** Submit a prompt. Queues if already executing (max 1 queued).
-     *  displayInput overrides what appears as the user message (e.g., "/audit" instead of full skill prompt).
-     *  rawInput is passed to Session.run() for hook matching (e.g., "/rulebased-harness:audit"). */
-    submit(input: string, displayInput?: string, rawInput?: string): Promise<void>;
-    /** Abort current execution and clear queue. */
-    abort(): void;
-    /** Cancel queued prompt without aborting current execution. */
-    cancelQueue(): void;
-    isExecuting(): boolean;
-    getPendingPrompt(): string | null;
-    getMessages(): TUniversalMessage[];
-    getStreamingText(): string;
-    getActiveTools(): IToolState[];
-    getContextState(): IContextWindowState;
-    getSession(): Session;
-    private executePrompt;
-    private handleTextDelta;
-    private handleToolExecution;
-    private clearStreaming;
-    private flushStreaming;
-    private buildResult;
-    private buildInterruptedResult;
-    private extractToolSummaries;
-    private trimCompletedTools;
-}
-
 /**
- * System commands — SDK-level command execution logic.
- *
- * Pure functions that operate on InteractiveSession.
- * No React, no TUI, no framework dependencies.
- * CLI wraps these as slash commands with UI chrome.
+ * Prompt the user for approval before running a tool.
  */
+declare function promptForApproval(terminal: ITerminalOutput, toolName: string, toolArgs: TToolArgs): Promise<boolean>;
 
-/** Result of a system command execution. */
-interface ICommandResult {
-    /** Human-readable output message */
-    message: string;
-    /** Command completed successfully */
-    success: boolean;
-    /** Additional structured data (command-specific) */
-    data?: Record<string, unknown>;
-}
-/** A system command with name, description, and execute logic. */
-interface ISystemCommand {
-    name: string;
-    description: string;
-    execute(session: InteractiveSession, args: string): Promise<ICommandResult> | ICommandResult;
-}
-/** Built-in system commands. */
-declare function createSystemCommands(): ISystemCommand[];
-/** Registry for system commands. */
-declare class SystemCommandExecutor {
-    private readonly commands;
-    constructor(commands?: ISystemCommand[]);
-    /** Register an additional command. */
-    register(command: ISystemCommand): void;
-    /** Execute a command by name. Returns null if command not found. */
-    execute(name: string, session: InteractiveSession, args: string): Promise<ICommandResult | null>;
-    /** List all registered commands. */
-    listCommands(): ISystemCommand[];
-    /** Check if a command exists. */
-    hasCommand(name: string): boolean;
-}
-
-export { AgentExecutor, BUILT_IN_AGENTS, BuiltinCommandSource, BundlePluginInstaller, BundlePluginLoader, CommandRegistry, DEFAULT_TOOL_DESCRIPTIONS, type IAgentDefinition, type IAgentExecutorOptions, type IAgentSession, type IAgentToolDeps, type IBundlePluginFeatures, type IBundlePluginInstallerOptions, type IBundlePluginManifest, type IBundleSkill, type ICommandResult, type ICommandSource, type ICreateSessionOptions, type IDiffLine, type IExecutionResult, type IInstalledPluginRecord, type IInstalledPluginsRegistry, type IInteractiveSessionEvents, type IInteractiveSessionOptions, type IKnownMarketplaceEntry, type IKnownMarketplacesRegistry, type ILoadedBundlePlugin, type ILoadedContext, type IMarketplaceClientOptions, type IMarketplaceManifest, type IMarketplacePluginEntry, type IMarketplaceSource, type IPluginSettings, type IProjectInfo, type IPromptExecutorOptions, type IPromptProvider, type IQueryOptions, type IResolvedConfig, type ISlashCommand, type ISubagentOptions, type ISubagentPromptOptions, type ISystemCommand, type ISystemPromptParams, type IToolState, type IToolSummary, InteractiveSession, MarketplaceClient, PluginSettingsStore, PromptExecutor, SkillCommandSource, SystemCommandExecutor, type TEnabledPlugins, type TInteractiveEventName, type TInteractivePermissionHandler, type TProviderFactory, type TSessionFactory, assembleSubagentPrompt, buildSystemPrompt, createAgentTool, createDefaultTools, createProvider, createSession, createSubagentLogger, createSubagentSession, createSystemCommands, detectProject, getBuiltInAgent, getForkWorkerSuffix, getSubagentSuffix, loadConfig, loadContext, parseFrontmatter, projectPaths, promptForApproval, query, resolveSubagentLogDir, retrieveAgentToolDeps, storeAgentToolDeps, userPaths };
+export { AgentExecutor, BUILT_IN_AGENTS, BuiltinCommandSource, BundlePluginInstaller, BundlePluginLoader, CommandRegistry, type IAgentDefinition, type IAgentExecutorOptions, type IAgentSession, type IAgentToolDeps, type IBundlePluginFeatures, type IBundlePluginInstallerOptions, type IBundlePluginManifest, type IBundleSkill, type ICommand, type ICommandResult, type ICommandSource, type ICreateQueryOptions, type IDiffLine, type IExecutionResult, type IInstalledPluginRecord, type IInstalledPluginsRegistry, type IInteractiveSessionEvents, type IInteractiveSessionOptions, type IKnownMarketplaceEntry, type IKnownMarketplacesRegistry, type ILoadedBundlePlugin, type IMarketplaceClientOptions, type IMarketplaceManifest, type IMarketplacePluginEntry, type IMarketplaceSource, type IPluginSettings, type IPromptExecutorOptions, type IPromptProvider, type ISubagentOptions, type ISubagentPromptOptions, type ISystemCommand, type IToolState, type IToolSummary, InteractiveSession, MarketplaceClient, PluginCommandSource, PluginSettingsStore, PromptExecutor, SkillCommandSource, type SkillPromptContext, type TEnabledPlugins, type TInteractiveEventName, type TInteractivePermissionHandler, type TPermissionResultValue, type TProviderFactory, type TSessionFactory, assembleSubagentPrompt, buildSkillPrompt, createAgentTool, createQuery, createSubagentLogger, createSubagentSession, getBuiltInAgent, getForkWorkerSuffix, getSubagentSuffix, parseFrontmatter, preprocessShellCommands, projectPaths, promptForApproval, resolveSubagentLogDir, retrieveAgentToolDeps, storeAgentToolDeps, substituteVariables, userPaths };