import type { ToolMetadata, MessagePartToolCall } from '@agforge/core';
/**
 * Agent 拦截器侧的执行锁接口。
 *
 * 与工具侧 `ToolExecutionLocker` 的区别：额外携带 `metadata` 和 `message` 参数，
 * 实现方可根据工具身份和调用上下文做差异化并发控制策略。
 *
 * `lock()` 返回一个解锁函数，工具完成资源操作后调用该函数释放锁。
 *
 * 本拦截器通过闭包将 `metadata` 和 `message` 自动绑定，
 * 转换为工具侧简化接口 `ToolExecutionLocker.lock(urn)`，工具无需感知元信息。
 */
export type ExecutionLocker = {
    /**
     * 锁定资源点，阻塞直到资源可用。
     *
     * @param urn 资源标识符（URL 格式）
     * @param metadata 工具元信息
     * @param message 工具调用消息
     * @returns 解锁函数，调用后释放资源锁
     */
    lock(urn: URL, metadata: ToolMetadata, message: MessagePartToolCall): Promise<() => void>;
};