package com.agent.management.engine;

/**
 * 节点执行过程中的流式事件回调。
 * executor 通过它实时推送各类增量片段，
 * 由引擎包装成 {@code node_stream} SSE 事件转发给前端。
 *
 * <p>v1.1 kind 取值与语义：</p>
 * <ul>
 *   <li>{@code thinking}        —— LLM 思考过程的增量 token，前端按 nodeId 聚合累加</li>
 *   <li>{@code tool_call}       —— 工具调用开始（content 为参数摘要）</li>
 *   <li>{@code tool_result}     —— 工具调用结束（content 为结果摘要）</li>
 *   <li>{@code status}          —— 实时状态文案（覆盖式，如"压缩上下文中"）</li>
 *   <li>{@code step}            —— 每轮 LLM 调用前进度（content 为 iteration+prev_tools JSON）</li>
 *   <li>{@code tool_progress}   —— 工具细粒度进度（content 为 event_type+preview JSON）</li>
 *   <li>{@code todo_update}     —— todo 工具完整输出（content 为完整 TODO JSON）</li>
 *   <li>{@code clarify_request} —— 模型请求用户确认（content 为 clarify_id+question+choices JSON）</li>
 * </ul>
 */
@FunctionalInterface
public interface NodeStreamSink {

    /**
     * @param nodeId   节点 ID
     * @param kind     事件类型：thinking | tool_call | tool_result | status | step | tool_progress | todo_update | clarify_request
     * @param content  增量内容（按 kind 语义填充）
     * @param toolName 工具名；kind != tool_* 时为 {@code null}
     */
    void emit(String nodeId, String kind, String content, String toolName);
}
