package com.agent.management.engine;

/**
 * 节点执行过程中的流式事件回调。
 * executor 通过它实时推送 thinking / tool_call / tool_result 增量片段，
 * 由引擎包装成 {@code node_stream} SSE 事件转发给前端。
 *
 * <p>语义：</p>
 * <ul>
 *   <li>{@code thinking}    —— LLM 思考过程的增量 token，前端应按 nodeId 聚合累加</li>
 *   <li>{@code tool_call}   —— 工具调用开始（content 为参数摘要）</li>
 *   <li>{@code tool_result} —— 工具调用结束（content 为结果摘要）</li>
 * </ul>
 */
@FunctionalInterface
public interface NodeStreamSink {

    /**
     * @param nodeId   节点 ID
     * @param kind     事件类型："thinking" | "tool_call" | "tool_result"
     * @param content  增量内容（thinking 片段 / 工具参数摘要 / 工具结果摘要）
     * @param toolName 工具名；kind != tool_* 时为 {@code null}
     */
    void emit(String nodeId, String kind, String content, String toolName);
}
