/**
 * @file Sandbox Prelude - 沙箱基础能力库
 * @description 注入到每个沙箱 _scripts/_prelude.cjs 的通用工具模块
 *              通过 runScript preamble 自动暴露为 global.sb
 *              让 LLM 只需编写业务逻辑，无需重复实现常用功能
 *
 * 可用能力:
 *   - HTTP: sb.fetch / sb.get / sb.post / sb.put / sb.head / sb.del
 *   - File I/O: sb.readJson / sb.writeJson / sb.readText / sb.writeText / sb.appendText / sb.readCsv / sb.writeCsv / sb.exists / sb.listDir
 *   - Data: sb.stats / sb.sum / sb.avg / sb.groupBy / sb.sortBy / sb.unique / sb.chunk / sb.range / sb.pick / sb.omit / sb.flatten
 *   - Date: sb.formatDate / sb.parseDate / sb.now / sb.daysAgo / sb.daysLater / sb.dateDiff
 *   - String: sb.template / sb.slugify / sb.truncate / sb.pad
 *   - Table: sb.markdownTable / sb.htmlTable
 *   - Logger: sb.log.info / sb.log.warn / sb.log.error / sb.log.debug
 *
 * == 扩展机制 ==
 * 基础能力可通过「扩展」机制注册，无需修改本文件：
 *   1. 全局注册（作用于所有沙箱）：
 *        import { registerSandboxPreludeExtension } from '@cicctencent/agent-server';
 *        registerSandboxPreludeExtension('myUtil', `
 *          module.exports = {
 *            greet(name) { return 'Hello, ' + name; },
 *          };
 *        `);
 *   2. 会话级注册（仅作用于单个沙箱）：
 *        sandboxManager.create(sessionId, { preludeExtensions: { myUtil: 'module.exports = { ... };' } });
 * 扩展模块需通过 module.exports 导出对象，prelude 会在加载时将其合并进 global.sb
 * （同名 key 会覆盖核心能力，便于定制）。扩展文件位于 _scripts/_prelude_ext/<name>.cjs。
 */
export interface SandboxPreludeExtension {
    /** 扩展名（仅允许 [a-zA-Z0-9_-]，用作文件名） */
    name: string;
    /** 扩展模块源码（CommonJS，需通过 module.exports 导出对象） */
    source: string;
}
/**
 * 注册一个沙箱基础能力扩展（全局生效，作用于之后创建的所有沙箱）
 * @param name 扩展名，仅允许 [a-zA-Z0-9_-]
 * @param source 扩展 CommonJS 源码，需通过 module.exports 导出对象
 * @example
 *   registerSandboxPreludeExtension('csv', `module.exports = { parse(text){ return text.split('\\n'); } };`);
 */
export declare function registerSandboxPreludeExtension(name: string, source: string): void;
/** 获取当前注册的所有扩展 */
export declare function getSandboxPreludeExtensions(): SandboxPreludeExtension[];
/** 清空所有已注册的扩展（主要用于测试） */
export declare function clearSandboxPreludeExtensions(): void;
/**
 * 读取 data/_shared/prelude/_prelude.cjs 作为对话沙箱 Node prelude 源码。
 * 自 change「prelude-shell-source-unification」起，对话沙箱不再内联 prelude 源码字符串，
 * init 阶段与 post-init 包装器同源，统一从 data/_shared/prelude 唯一源加载。
 * 缺失（受控资产丢失）时抛错，不静默回退到内联副本。
 */
export declare function loadNodeSandboxPreludeSource(): string;
/**
 * 读取 data/_shared/prelude/sb.sh 作为对话沙箱 Shell prelude 源码。
 * 自 change「prelude-shell-source-unification」起，sb.sh 的唯一源为 data/_shared/prelude/sb.sh，
 * 不再内联 SB_SH_SOURCE。init 阶段原样读取后写入运行目录 _scripts/sb.sh。
 * 运行时变量不烤入脚本：sb.sh 直接通过 ${SB_BACKEND_BASE_URL} 等从子进程 env 读取，
 * 与 Node(_prelude.cjs)、Python(sb.py) 三者对称。
 * 缺失（受控资产丢失）时抛错，不静默回退到内联副本。
 */
export declare function loadShellPreludeSource(): string;
/**
 * 确保 data/_shared/.env 存在：系统启动（或缺失）时依据 _shared/.env.tpl 生成一次。
 *
 * 该 .env 是运行时变量的唯一填值来源，供三类运行时统一读取：
 *   - Node(_prelude.cjs → require('./env.cjs'))：先读 .env 填空到 process.env，已有 env 不覆盖
 *   - Python(sb.py)：从 os.environ 读取（LocalSandbox 已注入子进程 env）
 *   - Shell(sb.sh)：从 ${SB_*} 读取（LocalSandbox 已注入子进程 env）
 *
 * 仅「缺失时」生成，不覆盖已有 .env（已文件为手动/历史填值优先）；生成失败时仅告警不阻断启动。
 */
export declare function ensureSharedEnv(): void;
//# sourceMappingURL=sandbox-prelude.d.ts.map