/**
 * SandboxToolEnv.ts — 工具沙箱执行环境（TypeScript 版）
 *
 * 为 AI 会话提供一个受控的工具执行上下文，包含：
 * - `copilot` 代理对象：通过属性访问调用任意已注册工具
 * - `processTemplate()`：展开 `${...}` 模板表达式
 * - `registerAPI()`：注册自定义 API（优先于 CopilotTools）
 * - 工具代理路由（toolProxy）：将指定工具委托给远程 agent
 * - 远程 agent 模式（remoteAgent）：所有工具调用发往远程 agent
 *
 * ## 使用示例
 * ```ts
 * const sandbox = new SandboxToolEnv(sdk, {
 *   workspace: 'myApp',
 *   enabledCategories: ['fileOps', 'execute', 'agent'],
 * });
 * sandbox.registerAPI('get_weather', async (city) => fetchWeather(city));
 * const expanded = await sandbox.processTemplate(
 *   'Current time: ${new Date().toLocaleString()}'
 * );
 * ```
 */
/**
 * 由 `copilot.restartAgent()` 在 `processTemplate()` 内部抛出的哨兵错误。
 * 调用方（如 DigitalHuman._sendViaText）捕获此信号后触发 agent 会话重启。
 */
export declare class RestartAgentSignal {
    readonly promptFile: string | null | undefined;
    readonly tools: string[] | undefined;
    readonly options: Record<string, unknown> | undefined;
    /** 便于跨 iframe 传递时识别此信号类型 */
    readonly isRestartAgentSignal = true;
    /**
     * @param promptFile - 新会话要加载的配置文件 URL 或路径（null/undefined 表示使用默认）
     * @param tools      - 新会话启用的工具分类列表（undefined 表示继承）
     * @param options    - 高级重启选项（minigameSlot / frameOptions 等）
     */
    constructor(promptFile?: string | null, tools?: string[], options?: Record<string, unknown>);
}
/** 工具代理路由配置 */
export interface ToolProxyRoute {
    /** 目标 agent 名称 */
    agent: string;
    /** 可选：任务描述 */
    task?: string;
}
/** SandboxToolEnv 构造选项 */
export interface SandboxToolEnvOptions {
    /** 文件操作工作空间名（对应 personalPageStore 的 workspace 参数） */
    workspace?: string;
    /** 只读回退目录（挂载的外部公开文件夹） */
    mountFolder?: unknown;
    /** 启用的 CopilotTools 分类（默认 ['fileOps', 'execute']） */
    enabledCategories?: string[];
    /** 远程 agent 名称（设置后所有工具调用委托给该 agent） */
    remoteAgent?: string;
    /** 远程模式下授权的工具分类列表 */
    categories?: string[];
    /** 工具代理路由配置 */
    toolProxy?: {
        /** 按函数名代理：`{ 'read_file': { agent: 'fileAgent' } }` */
        functions?: Record<string, ToolProxyRoute>;
        /** 按分类代理：`{ 'fileOps': { agent: 'fileAgent' } }` */
        categories?: Record<string, ToolProxyRoute>;
    };
    /** 关联的 ChatSession（允许工具通过 config._session 访问） */
    session?: AgentSessionRef;
}
/** ChatSession 最小接口（避免循环引用） */
interface AgentSessionRef {
    name?: string;
    workspace?: string;
    _restartSignal?: unknown;
    sandbox?: unknown;
    [key: string]: unknown;
}
/** SDK 最小接口 */
interface SDKRef {
    copilotTools?: {
        execute: (name: string, args: unknown, config: unknown) => Promise<unknown>;
        getToolDefinitions: (categories: string[]) => unknown[];
        _fnNameToCategory?: Record<string, string>;
        _registry?: Record<string, {
            disableAutoProxy?: boolean;
        }>;
    };
    agentRouter?: {
        hasAgent: (name: string) => boolean;
        waitForAgent: (name: string) => Promise<void>;
        submitTask: (name: string, payload: unknown) => Promise<unknown>;
    };
}
declare class SandboxToolEnv {
    readonly sdk: SDKRef;
    workspace: string;
    mountFolder: unknown;
    enabledCategories: string[];
    session: AgentSessionRef | null;
    remoteAgent: string | null;
    categories: string[];
    _activePromptFile: string | null;
    _templateSourceFile: string | null;
    private _customAPIs;
    private _copilotProxy;
    private _toolProxy;
    private _cachedDefinitions;
    constructor(sdk: SDKRef, options?: SandboxToolEnvOptions);
    /**
     * copilot 代理对象：通过属性访问（如 `copilot.read_file(...)`）调用任意工具。
     * 解析顺序：自定义 API → 工具代理（toolProxy）→ CopilotTools 内置工具。
     */
    get copilot(): Record<string, (...args: unknown[]) => Promise<string>>;
    /**
     * 注册自定义可调用 API（优先于同名 CopilotTools 工具）。
     * 注册后 `copilot.myTool(args)` 将直接调用此函数。
     *
     * @param name - 工具/函数名称
     * @param fn   - 异步回调函数 `(...args) => result`
     */
    registerAPI(name: string, fn: (...args: unknown[]) => Promise<unknown>): void;
    /**
     * 执行指定工具。
     * - 远程 agent 模式：委托给 remoteAgent
     * - 自定义 API：直接调用
     * - 工具代理：通过 AgentRouter 路由到远程 agent
     * - 内置工具：调用 sdk.copilotTools.execute
     *
     * @param fnName     - 工具/函数名称
     * @param fnArgs     - 参数对象
     * @param extraConfig - 附加配置（如 { _session }）
     */
    execute(fnName: string, fnArgs: unknown, extraConfig?: Record<string, unknown>): Promise<unknown>;
    /**
     * 获取已启用分类的 OpenAI 格式工具定义。
     * 远程 agent 模式下从远端获取（带缓存）。
     *
     * @param forceRefresh - 是否强制刷新远程缓存（默认 false）
     */
    getToolDefinitions(forceRefresh?: boolean): Promise<unknown[]> | unknown[];
    /** 检查沙箱是否可用（远程模式下检查 agent 是否已连接）。 */
    isAvailable(): boolean;
    /** 从远程 agent 获取所有可用工具分类列表。 */
    getCategories(): Promise<unknown>;
    /**
     * 批量顺序执行工具调用，收集所有结果。
     *
     * @param calls - 工具调用列表 `[{ tool, args }]`
     */
    executeBatch(calls?: Array<{
        tool: string;
        args?: unknown;
    }>): Promise<Array<{
        tool: string;
        success: boolean;
        result?: unknown;
        error?: string;
    }>>;
    /** 清除远程工具定义缓存。 */
    clearCache(): void;
    /**
     * 在沙箱上下文中运行任意 async JavaScript 代码。
     * 代码可访问 `copilot` 代理和 `context` 中的所有键。
     *
     * @param code    - 要执行的 JavaScript 代码字符串
     * @param context - 注入到执行上下文的变量映射
     */
    runCode(code: string, context?: Record<string, unknown>): Promise<unknown>;
    /**
     * 展开文本中的 `${...}` 模板表达式。
     * 表达式可使用 `copilot` 代理和 `await`。
     * 支持最多 3 层嵌套递归展开。
     * 表达式执行出错时保留原始 `${...}` 标记不变。
     *
     * 示例：
     * ```ts
     * const result = await sandbox.processTemplate(
     *   'Notes: ${await copilot.read_file("notes.md", 1, 50)}'
     * );
     * ```
     *
     * @param text   - 包含 `${...}` 表达式的模板字符串
     * @param _depth - 内部递归深度计数器（请勿手动传入）
     */
    processTemplate(text: string, _depth?: number): Promise<string>;
    /** @private 解析函数名对应的工具代理路由。 */
    private _resolveToolProxy;
    /** @private 通过 AgentRouter 将工具调用代理给远程 agent（绕过 LLM）。 */
    private _executeViaProxy;
    /** @private 从远程 agent 获取工具定义（带缓存）。 */
    private _getRemoteToolDefinitions;
    /** @private 在远程 agent 模式下执行工具调用。 */
    private _executeRemote;
    /** @private 向远程 agent 提交任务（via AgentRouter.submitTask）。 */
    private _submitRemoteTask;
    /** @private 将任意工具执行结果规范化为字符串。 */
    private _normalizeToolResult;
    /** @private 构建 runCode 的执行上下文（注入 copilot 代理和 context 键）。 */
    private _createRunCodeContext;
    /** @private 将代码包装为 AsyncFunction（优先尝试表达式形式，回退语句形式）。 */
    private _createCodeRunner;
    /** @private 检查字符串是否为合法 JS 标识符（用于安全注入执行上下文）。 */
    private _isValidIdentifier;
    /**
     * @private 构建 copilot Proxy——将属性访问映射到工具调用。
     * 内置常用工具（read_file / list_dir 等）的位置参数自动转换为命名参数。
     */
    private _buildProxy;
}
export default SandboxToolEnv;
//# sourceMappingURL=SandboxToolEnv.d.ts.map