autosnippet/dist/lib/agent/core/ToolExecutionPipeline.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * ToolExecutionPipeline — 工具执行的中间件管道
 *
 * 将 reactLoop 中 ~120 行的工具执行逻辑拆分为独立中间件:
 *   before → execute → after
 *
 * 每个中间件负责一个横切关注点:
 *   1. EventBusPublisher — 事件发布
 *   2. ProgressEmitter — 进度回调
 *   3. SafetyGate — SafetyPolicy 安全拦截
 *   4. CacheCheck — MemoryCoordinator 缓存命中
 *   5. ObservationRecord — 记忆记录
 *   6. TrackerSignal — ExplorationTracker 信号收集
 *   7. TraceRecord — ActiveContext 推理链记录
 *   8. SubmitDedup — 提交去重
 *
 * @module core/ToolExecutionPipeline
 */
import type { AgentRuntime } from '../AgentRuntime.js';
import type { LoopContext } from './LoopContext.js';
/** 工具调用描述 */
interface ToolCall {
    name: string;
    args: Record<string, unknown>;
    id: string;
}
/** 工具执行上下文 */
interface ToolExecContext {
    runtime: AgentRuntime;
    loopCtx: LoopContext;
    iteration: number;
}
/** 工具执行元数据 */
interface ToolMetadata {
    cacheHit: boolean;
    blocked: boolean;
    isNew: boolean;
    durationMs: number;
    dedupMessage?: string;
    isSubmit?: boolean;
}
/** before 钩子返回值 */
interface BeforeVerdict {
    blocked?: boolean;
    result?: unknown;
}
/** 工具中间件 */
interface ToolMiddleware {
    name: string;
    before?: (call: ToolCall, ctx: ToolExecContext, metadata: ToolMetadata) => BeforeVerdict | undefined | void | Promise<BeforeVerdict | undefined | void>;
    after?: (call: ToolCall, result: unknown, ctx: ToolExecContext, metadata: ToolMetadata) => void | Promise<void>;
}
export declare class ToolExecutionPipeline {
    #private;
    /** 注册中间件 */
    use(middleware: ToolMiddleware): this;
    /**
     * 执行单个工具调用
     *
     * 执行流:
     *   1. 依次调用 before 钩子 — 任一返回 blocked/result 则短路
     *   2. 实际执行工具 (toolRegistry.execute)
     *   3. 依次调用 after 钩子
     *
     * @param call { name, args, id }
     * @param context { runtime, loopCtx, iteration }
     * @returns >}
     */
    execute(call: ToolCall, context: ToolExecContext): Promise<{
        result: unknown;
        metadata: ToolMetadata;
    }>;
}
/**
 * AllowlistGate — 工具白名单守卫
 *
 * 防止 LLM hallucinate 不在当前 capability 允许列表中的工具调用。
 * 从 LoopContext.toolSchemas 中提取允许的工具名列表，
 * 拒绝不在列表中的调用（返回 error 提示）。
 *
 * Forge 集成：不在白名单的工具如果已由 ToolForge 锻造（存在于 ToolRegistry），则放行。
 *
 * before: 如果工具不在白名单中且非锻造工具则短路返回 error
 */
export declare const allowlistGate: {
    name: string;
    before(call: ToolCall, ctx: ToolExecContext): BeforeVerdict | undefined;
};
/**
 * SafetyGate — SafetyPolicy 安全拦截
 *
 * before: 如果策略拒绝则短路返回 error
 */
export declare const safetyGate: {
    name: string;
    before(call: ToolCall, ctx: ToolExecContext): BeforeVerdict | undefined;
};
/**
 * CacheCheck — MemoryCoordinator 缓存命中
 *
 * before: 如果缓存命中则短路返回缓存值
 */
export declare const cacheCheck: {
    name: string;
    before(call: ToolCall, ctx: ToolExecContext): BeforeVerdict | undefined;
};
/**
 * ObservationRecord — MemoryCoordinator 观察记录
 *
 * after: 记录工具执行观察
 */
export declare const observationRecord: {
    name: string;
    after(call: ToolCall, result: unknown, ctx: ToolExecContext, meta: ToolMetadata): void;
};
/**
 * TrackerSignal — ExplorationTracker 信号收集
 *
 * after: 记录工具调用信号，更新 isNew 标记
 */
export declare const trackerSignal: {
    name: string;
    after(call: ToolCall, result: unknown, ctx: ToolExecContext, meta: ToolMetadata): void;
};
/**
 * TraceRecord — ActiveContext 推理链记录
 *
 * after: 记录 Action + Observation 到推理链
 */
export declare const traceRecord: {
    name: string;
    after(call: ToolCall, result: unknown, ctx: ToolExecContext, meta: ToolMetadata): void;
};
/**
 * SubmitDedup — 提交去重
 *
 * after: 检查并标记重复提交 (修改 metadata)
 */
export declare const submitDedup: {
    name: string;
    after(call: ToolCall, result: unknown, ctx: ToolExecContext, meta: ToolMetadata): void;
};
/**
 * ProgressEmitter — 进度回调 (可选，需 runtime.emitProgress 为 public)
 *
 * NOTE: 默认管道不包含此中间件，因为 tool_end 事件需要 resultStr.length，
 * 而 resultStr 在管道外部计算。由 #processToolCalls 直接处理。
 */
export declare const progressEmitter: {
    name: string;
    before(call: ToolCall, ctx: ToolExecContext): void;
    after(call: ToolCall, result: unknown, ctx: ToolExecContext, meta: ToolMetadata): void;
};
/**
 * EventBusPublisher — EventBus 事件发布 (可选)
 *
 * NOTE: 默认管道不包含此中间件。由 #processToolCalls 直接处理，
 * 与原始 reactLoop 保持完全一致的事件顺序。
 */
export declare const eventBusPublisher: {
    name: string;
    before(call: ToolCall, ctx: ToolExecContext): void;
    after(call: ToolCall, result: unknown, ctx: ToolExecContext, meta: ToolMetadata): void;
};
/**
 * 创建预配置的工具执行管道
 *
 * 中间件顺序:
 *   1. safetyGate (安全拦截 — 可短路)
 *   2. cacheCheck (缓存检查 — 可短路)
 *   3. observationRecord (记忆记录)
 *   4. trackerSignal (信号收集)
 *   5. traceRecord (推理链)
 *   6. submitDedup (提交去重)
 *
 * NOTE: eventBusPublisher 和 progressEmitter 不在默认管道中，
 * 由 #processToolCalls 直接处理，以保持与原始 reactLoop 完全一致的事件顺序
 * (progress_end 需要 resultStr.length，在管道外计算)。
 */
export declare function createToolPipeline(): ToolExecutionPipeline;
export {};