import type { ToolMetadata, MessagePartToolCall } from '@agforge/core';
/**
 * 框架层全局执行锁接口。
 *
 * 与 `ExecutionLocker` 的区别：不接受 `urn` 参数，由框架层在每个工具执行前自动调用。
 * 用于实现全局的并发控制策略（如按工具名串行、全局串行等），
 * 而非工具主动申请特定资源的锁。
 *
 * 默认实现为 `PerToolSerialLocker`（同名工具串行，不同工具并行）。
 * 若需完全禁用框架层锁，可使用 `NoopGlobalExecutionLocker`。
 *
 * `lock()` 返回一个解锁函数，工具执行完成后框架自动调用以释放锁。
 */
export type GlobalExecutionLocker = {
    /**
     * 锁定工具执行，阻塞直到可以执行。
     *
     * @param metadata 工具元信息
     * @param message 工具调用消息
     * @returns 解锁函数，调用后释放锁
     */
    lock(metadata: ToolMetadata, message: MessagePartToolCall): Promise<() => void>;
};