events

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 2, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package events 定义共享的运行时事件契约。

此包包含:

  • 用于 API 和引擎接口的稳定运行时事件契约 (agent.Event, agent.EventType)

Index

Constants

View Source 
const (
	// EventStarted is the business run started event.
	EventStarted agent.EventType = "run.started"
	// EventCompleted is the business run completed event.
	EventCompleted agent.EventType = "run.completed"
	// EventFailed is the business run failed event.
	EventFailed agent.EventType = "run.failed"
	// EventCancelled is the business run cancelled event.
	EventCancelled agent.EventType = "run.cancelled"

	// EventInvocationStarted indicates a provider invocation has started.
	EventInvocationStarted agent.EventType = "provider.started"
	// EventInvocationCompleted indicates a provider invocation completed.
	EventInvocationCompleted agent.EventType = "provider.completed"
	// EventInvocationFailed indicates a provider invocation failed.
	EventInvocationFailed agent.EventType = "provider.failed"
	// EventInvocationCancelled indicates a provider invocation was cancelled.
	EventInvocationCancelled agent.EventType = "provider.cancelled"

	// EventMessageDelta 包含可读的助手输出。
	EventMessageDelta agent.EventType = "message.delta"
	// EventReasoningDelta 包含推理输出（如有）。
	EventReasoningDelta agent.EventType = "reasoning.delta"
	// EventResult 包含运行时运行的最终助手结果。
	EventResult agent.EventType = "message.result"
	// EventMessageComplete 表示消息已完成（包含完整内容）。
	EventMessageComplete agent.EventType = "message.complete"

	// EventToolCallStarted 表示工具调用已开始。
	EventToolCallStarted agent.EventType = "tool_call.started"
	// EventToolCallDelta 表示工具调用增量内容。
	EventToolCallDelta agent.EventType = "tool_call.delta"
	// EventToolCallCompleted 表示工具调用已完成。
	EventToolCallCompleted agent.EventType = "tool_call.completed"
	// EventToolCallResult 表示工具调用最终结果。
	EventToolCallResult agent.EventType = "tool_call.result"
	// EventToolCallFailed 表示工具调用失败。
	EventToolCallFailed agent.EventType = "tool_call.failed"

	// EventTodoSnapshot 包含当前运行的完整运行时待办列表。
	EventTodoSnapshot agent.EventType = "todo.snapshot"
	// EventTodoUpdated 包含更新后的完整运行时待办列表。
	EventTodoUpdated agent.EventType = "todo.updated"

	// EventArtifactDeclared indicates a generated artifact was declared by the runtime.
	EventArtifactDeclared agent.EventType = "artifact.declared"

	// EventApprovalRequested indicates the engine needs user approval for a tool call.
	EventApprovalRequested agent.EventType = "approval.requested"
	// EventApprovalResolved indicates an approval request has been resolved.
	EventApprovalResolved agent.EventType = "approval.resolved"

	// EventQuestionAsked indicates the engine is asking the user a clarifying question.
	EventQuestionAsked agent.EventType = "question.asked"
	// EventQuestionAnswered indicates a question has been answered by the user.
	EventQuestionAnswered agent.EventType = "question.answered"

	// EventWorkTitleUpdated indicates project/task titles were auto-generated after the first message.
	EventWorkTitleUpdated agent.EventType = "work.title.updated"

	// EventPlanPublished indicates a plan file was uploaded to object storage.
	EventPlanPublished agent.EventType = "plan.published"

	// EventProviderSessionStarted indicates the provider exposed a native session ID.
	EventProviderSessionStarted agent.EventType = "provider_session.started"
)

Variables

This section is empty.

Functions

func DecodePayload 

func DecodePayload[T any](event *agent.Event) (T, error)

DecodePayload 从事件中解码结构化载荷。

func MarshalRaw 

func MarshalRaw(value any) json.RawMessage

MarshalRaw encodes a dynamic provider value at the JSON protocol boundary.

func NewApprovalRequested 

func NewApprovalRequested(payload ApprovalRequestPayload) *agent.Event

NewApprovalRequested creates an approval request event.

func NewApprovalResolved 

func NewApprovalResolved(payload ApprovalDecisionPayload) *agent.Event

NewApprovalResolved creates an approval resolution event.

func NewArtifactDeclared 

func NewArtifactDeclared(payload ArtifactPayload) *agent.Event

NewArtifactDeclared 创建语义化的产物声明事件。

func NewMessageDelta 

func NewMessageDelta(messageID string, content string) *agent.Event

NewMessageDelta 创建标准的助手消息增量事件。

func NewMessageResult 

func NewMessageResult(message string, usage *agent.Usage) *agent.Event

NewMessageResult 创建标准的最终助手结果事件。

func NewPlanPublished added in v0.1.19 

func NewPlanPublished(payload PlanPublishedPayload) *agent.Event

NewPlanPublished creates a plan published event.

func NewQuestionAnswered 

func NewQuestionAnswered(payload QuestionAnswerPayload) *agent.Event

NewQuestionAnswered creates a question answered event.

func NewQuestionAsked 

func NewQuestionAsked(payload QuestionRequestPayload) *agent.Event

NewQuestionAsked creates a question asked event.

func NewReasoningDelta 

func NewReasoningDelta(messageID string, content string) *agent.Event

NewReasoningDelta 创建标准的推理增量事件。

func NewTodoSnapshot 

func NewTodoSnapshot(items []RuntimeTodoItem) *agent.Event

NewTodoSnapshot 创建标准的完整待办快照事件。

func NewTodoUpdated 

func NewTodoUpdated(items []RuntimeTodoItem) *agent.Event

NewTodoUpdated 创建标准的完整待办更新事件。

func NewToolCallCompleted 

func NewToolCallCompleted(toolCallID string, name string, result json.RawMessage, elapsedMS int64) *agent.Event

NewToolCallCompleted 创建标准的成功工具调用终止事件。

func NewToolCallFailed 

func NewToolCallFailed(toolCallID string, name string, message string, elapsedMS int64) *agent.Event

NewToolCallFailed 创建标准的失败工具调用终止事件。

func NewToolCallStarted 

func NewToolCallStarted(toolCallID string, name string, arguments json.RawMessage) *agent.Event

NewToolCallStarted 创建标准的工具调用开始事件。

Types

type ApprovalDecisionPayload 

type ApprovalDecisionPayload struct {
	RequestID string `json:"request_id"`
	Action    string `json:"action"` // "approve" | "deny" | "always"
	Reason    string `json:"reason,omitempty"`
}

ApprovalDecisionPayload describes the outcome of an approval request.

type ApprovalRequestPayload 

type ApprovalRequestPayload struct {
	RequestID   string            `json:"request_id"`
	ToolName    string            `json:"tool_name"`
	ToolCallID  string            `json:"tool_call_id,omitempty"`
	Description string            `json:"description"`
	Arguments   json.RawMessage   `json:"arguments,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

ApprovalRequestPayload describes a tool call that needs user approval. 前端统一结构，不区分引擎类型。引擎特有信息放在 Metadata 中。

type ArtifactPayload 

type ArtifactPayload struct {
	ArtifactID   string    `json:"artifact_id,omitempty"`
	Title        string    `json:"title,omitempty"`
	Filename     string    `json:"filename,omitempty"`
	OriginalName string    `json:"original_name,omitempty"`
	Description  string    `json:"description,omitempty"`
	MimeType     string    `json:"mime_type,omitempty"`
	ArtifactType string    `json:"artifact_type,omitempty"`
	FileSize     int64     `json:"file_size,omitempty"`
	CreatedAt    time.Time `json:"created_at,omitempty"`
	RelativePath string    `json:"relative_path,omitempty"`
	StorageKey   string    `json:"storage_key,omitempty"`
	StorageURI   string    `json:"storage_uri,omitempty"`
	Sha256       string    `json:"sha256,omitempty"`
	Source       string    `json:"source,omitempty"`
	Status       string    `json:"status,omitempty"`
}

ArtifactPayload 引用单次运行产生的产物。

type ChannelSink 

type ChannelSink struct {
	C chan<- *agent.Event
}

ChannelSink 将事件发送到通道，适用于 SSE/WebSocket 适配器。

func (ChannelSink) Emit 

func (s ChannelSink) Emit(ctx context.Context, event *agent.Event) error

Emit 发送事件，不会因断开连接的消费者而永久阻塞。

type Emitter 

type Emitter struct {
	// contains filtered or unexported fields
}

Emitter 填充通用事件元数据并将事件转发到 Sink。

func NewEmitter 

func NewEmitter(runID string, traceID string, sink Sink) *Emitter

NewEmitter 创建运行范围的事件发射器。

func (*Emitter) Emit 

func (e *Emitter) Emit(ctx context.Context, event *agent.Event) error

Emit 在填充稳定的元数据后转发一个事件。

type MessageDeltaPayload 

type MessageDeltaPayload struct {
	MessageID string `json:"message_id,omitempty"`
	Role      string `json:"role,omitempty"`
	Content   string `json:"content"`
}

MessageDeltaPayload 是助手文本增量的标准负载。

type MessageIDMapper 

type MessageIDMapper struct {
	// contains filtered or unexported fields
}

MessageIDMapper 在一次运行中将提供者消息标识符映射到 Leros 消息 ID。

func NewMessageIDMapper 

func NewMessageIDMapper() *MessageIDMapper

NewMessageIDMapper 创建一次运行时执行的映射器。

func (*MessageIDMapper) CurrentOrNew 

func (m *MessageIDMapper) CurrentOrNew() string

CurrentOrNew 返回当前消息 ID，如有需要则创建。

func (*MessageIDMapper) ForProvider 

func (m *MessageIDMapper) ForProvider(providerID string) string

ForProvider 返回提供者本地消息 ID 对应的稳定 Leros 消息 ID。

func (*MessageIDMapper) StartNew 

func (m *MessageIDMapper) StartNew() string

StartNew 创建一个新的消息 ID 并将其标记为当前。

type MessageResultPayload 

type MessageResultPayload struct {
	Message string       `json:"message,omitempty"`
	Usage   *agent.Usage `json:"usage,omitempty"`
}

MessageResultPayload 描述最终助手结果和可选的使用情况元数据。

type PlanPublishedPayload added in v0.1.19 

type PlanPublishedPayload struct {
	FileID       string `json:"file_id"`
	Directive    string `json:"directive"`     // :::plan{...} 完整指令
	SummaryLines int    `json:"summary_lines"` // 摘要行数（固定20）
	TotalLines   int    `json:"total_lines"`   // 总行数
	// RecordUpload 所需字段
	StorageKey   string `json:"storage_key,omitempty"`
	StorageURI   string `json:"storage_uri,omitempty"`
	Filename     string `json:"filename,omitempty"`
	OriginalName string `json:"original_name,omitempty"`
	MimeType     string `json:"mime_type,omitempty"`
	FileSize     int64  `json:"file_size,omitempty"`
	Sha256       string `json:"sha256,omitempty"`
}

PlanPublishedPayload carries the uploaded plan file info and :::plan directive.

type QuestionAnswerPayload 

type QuestionAnswerPayload struct {
	RequestID string     `json:"request_id"`
	Answers   [][]string `json:"answers"`
}

QuestionAnswerPayload describes the user's answer to a question request.

type QuestionItem 

type QuestionItem struct {
	Question    string           `json:"question"`
	Header      string           `json:"header,omitempty"`
	Options     []QuestionOption `json:"options"`
	MultiSelect bool             `json:"multiple"`
	Custom      bool             `json:"custom"`
}

QuestionItem is a single question within a question request.

type QuestionOption 

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

QuestionOption is a choice option for a question.

type QuestionRequestPayload 

type QuestionRequestPayload struct {
	RequestID       string            `json:"request_id"`
	SessionID       string            `json:"session_id,omitempty"`
	Questions       []QuestionItem    `json:"questions"`
	ToolCallID      string            `json:"tool_call_id,omitempty"`
	MessageID       string            `json:"message_id,omitempty"`
	InteractionType string            `json:"interaction_type,omitempty"`
	Metadata        map[string]string `json:"metadata,omitempty"`
}

QuestionRequestPayload describes a clarifying question from the engine to the user.

type RunEventRecord 

type RunEventRecord struct {
	Seq       int64           `json:"seq,omitempty"`
	LastSeq   int64           `json:"last_seq,omitempty"`
	Type      agent.EventType `json:"type"`
	Timestamp int64           `json:"timestamp,omitempty"`
	Payload   json.RawMessage `json:"payload,omitempty"`
}

RunEventRecord 是归一化、已归档的运行时事件。

type RuntimeTodoItem 

type RuntimeTodoItem struct {
	ID       string `json:"id"`
	Title    string `json:"title"`
	Status   string `json:"status"`
	Priority string `json:"priority,omitempty"`
}

RuntimeTodoItem 描述一个运行时本地规划步骤。

type Sink 

type Sink interface {
	Emit(ctx context.Context, event *agent.Event) error
}

Sink 接收执行期间发出的运行时事件。

func NewLogSink 

func NewLogSink() Sink

NewLogSink 返回一个将运行事件写入调试日志的接收器。

func NewNoopSink 

func NewNoopSink() Sink

NewNoopSink 返回一个丢弃所有事件的接收器。

type SinkFunc 

type SinkFunc func(ctx context.Context, event *agent.Event) error

SinkFunc 将函数适配为 Sink。

func (SinkFunc) Emit 

func (f SinkFunc) Emit(ctx context.Context, event *agent.Event) error

Emit 调用 f(ctx, event)。

type ToolCallPayload 

type ToolCallPayload struct {
	ToolCallID string          `json:"tool_call_id"`
	Name       string          `json:"name"`
	Arguments  json.RawMessage `json:"arguments,omitempty"`
}

ToolCallPayload 是工具调用开始和参数事件的标准负载。

type ToolCallResultPayload 

type ToolCallResultPayload struct {
	ToolCallID string          `json:"tool_call_id"`
	Name       string          `json:"name,omitempty"`
	Result     json.RawMessage `json:"result,omitempty"`
	Error      string          `json:"error,omitempty"`
	IsError    bool            `json:"is_error"`
	ElapsedMS  int64           `json:"elapsed_ms,omitempty"`
}

ToolCallResultPayload 是工具调用终止事件的标准负载。

type WorkTitleUpdatedPayload 

type WorkTitleUpdatedPayload struct {
	ProjectID    string `json:"project_id"`
	ProjectName  string `json:"project_name"`
	TaskID       string `json:"task_id,omitempty"`
	TaskTitle    string `json:"task_title,omitempty"`
	SessionID    string `json:"session_id"`
	SessionTitle string `json:"session_title,omitempty"`
}

WorkTitleUpdatedPayload notifies clients that project/task titles were auto-generated.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.