agent

type AgentEndedPayload ¶ added in v0.1.22

type AgentEndedPayload struct {
	ProviderSessionID string `json:"provider_session_id,omitempty"`
}

AgentEndedPayload signals that the agent execution has ended.

type AgentStartedPayload ¶ added in v0.1.22

type AgentStartedPayload struct {
	ProviderSessionID string `json:"provider_session_id"`
}

AgentStartedPayload signals that the agent started and exposed a native provider session ID.

type ApprovalDecision ¶

type ApprovalDecision struct {
	RequestID string
	Action    string // "approve" | "deny" | "always"
	Reason    string
}

ApprovalDecision is the user's response to an approval request.

type ApprovalRequest ¶

type ApprovalRequest struct {
	RequestID   string
	ToolCallID  string
	ToolName    string
	Arguments   json.RawMessage
	Description string
	Runtime     string
}

ApprovalRequest carries the details needed for an approval decision.

type ApprovalRequestedPayload ¶ added in v0.1.22

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

ApprovalRequestedPayload describes a tool call that needs user approval.

type ApprovalResolvedPayload ¶ added in v0.1.22

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

ApprovalResolvedPayload describes the outcome of an approval request.

type ApprovalResponder ¶ added in v0.1.22

type ApprovalResponder interface {
	WriteDecision(requestID string, action string) error
}

ApprovalResponder writes an approval decision back to a provider runtime.

type Attachment ¶ added in v0.3.9

type Attachment struct {
	MIME string
	// Name is the display filename (e.g. "头像.jpeg"); it is not a path.
	Name string
	Data []byte
}

Attachment is a multimodal file (e.g. an image) supplied with one execution. Data holds the raw bytes when the file is inlined (e.g. embedded as a base64 data URL); runtimes decide how to attach them. When Data is empty, the file may still be materialized on disk under Filesystem.UploadRelDir, which the runtime can combine with Name to locate it. It is intended for vision/multimodal-capable inputs only — plain text attachments should stay in the prompt.

type ExecutionMode ¶ added in v0.1.18

type ExecutionMode string

ExecutionMode controls runtime behavior independently from any host business model.

const (
	// ExecutionModeDefault keeps the runtime's normal execution behavior.
	ExecutionModeDefault ExecutionMode = "default"
	// ExecutionModePlan requests planning behavior when the runtime supports it.
	ExecutionModePlan ExecutionMode = "plan"
)

type ExecutionPolicy ¶

type ExecutionPolicy struct {
	PermissionMode string
	AllowedTools   []string
}

ExecutionPolicy controls generic runtime behavior.

type ExecutionRequest ¶

type ExecutionRequest struct {
	ExecutionID string
	TraceID     string
	Runtime     string
	SessionKey  string
	InstanceKey string
	Mode        ExecutionMode

	SystemPrompt    string
	Prompt          string
	Messages        []Message
	Attachments     []Attachment
	Model           ModelConfig
	Tools           []Tool
	MCPServers      []MCPServerConfig
	ExtraEnv        []string
	Policy          ExecutionPolicy
	Filesystem      FilesystemContext
	ProviderSession ProviderSession
}

ExecutionRequest is a fully prepared, business-neutral Runtime input.

type ExecutionResult ¶

type ExecutionResult struct {
	Message                string
	Usage                  *Usage
	ToolCalls              []ToolCallRecord
	ProviderConversationID string
}

ExecutionResult is the low-level result returned by a Runtime before business finalization.

type Executor ¶

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

Executor resolves a Runtime by name and drives the execution lifecycle:

1. Validate the execution request.
2. Resolve a Runtime implementation by name.
3. Wrap observer in SerialObserver for ordered, serial event delivery.
4. Call Runtime.Execute with the SerialObserver.
5. Return ExecutionResult.

Executor does NOT emit execution lifecycle events. The function return value (ExecutionResult, error) expresses success, failure, or cancellation.

func NewExecutor(registry *Registry) *Executor

func (e *Executor) Execute(
	ctx context.Context,
	request ExecutionRequest,
	observer NodeObserver,
) (ExecutionResult, error)

func (e *Executor) ResolveRuntimeKind(kind string) (string, error)

type FilesystemContext ¶

type FilesystemContext struct {
	WorkDir  string
	RepoDir  string
	TaskDir  string
	SkillDir string
	// UploadRelDir is the workspace-relative subdirectory (relative to RepoDir)
	// where attachments are materialized on disk, e.g. "uploads". Runtimes may
	// combine it with an Attachment.Name to locate a non-inlined attachment.
	// It is empty when no uploads directory is provisioned.
	UploadRelDir string
}

FilesystemContext contains the already prepared runtime directories.

type InteractionHandler ¶

type InteractionHandler interface {
	// RequestApproval asks for user approval on a tool call.
	// It blocks until a decision is made or the context is cancelled.
	RequestApproval(ctx context.Context, req *ApprovalRequest) (*ApprovalDecision, error)

	// RequestAnswer asks the user to answer a set of questions.
	// It blocks until answers are received or the context is cancelled.
	RequestAnswer(ctx context.Context, req *QuestionRequest) (*QuestionAnswer, error)
}

InteractionHandler handles approval and question requests from a Runtime. It is injected at Runtime construction time; Runtime MUST NOT depend on a package-level default.

type InteractionWaitObserver ¶ added in v0.3.9

type InteractionWaitObserver interface {
	// BeginInteractionWait 开始一次交互等待。
	// 返回的 end 用于在等待结束后释放交互槽并重新获取计算槽；
	// 仅在等待正常结束时需要调用，ctx 取消时无需调用。
	// 交互等待容量已满时返回错误，调用方应以明确错误结束任务。
	BeginInteractionWait(
		ctx context.Context,
		requestID string,
		kind string,
	) (end func() error, err error)
}

InteractionWaitObserver 观察并参与一个交互等待（审批/问答）的生命周期。

调用方在某个交互请求阻塞等待用户的决策/回答前调用 BeginInteractionWait， 并在等待结束后调用返回的 end。Coordinator 通过该接口实现计算槽的 释放/重取与交互等待容量的核算：

运行任务占用计算槽
  -> 触发 approval/question
  -> 进入交互等待槽（BeginInteractionWait）
  -> 释放计算槽
  -> 用户响应或超时
  -> end() 重新获取计算槽
  -> Runtime 继续执行

该接口由 Coordinator 注入到运行 ctx（见 WithInteractionWaitObserver）； 未注入时 Behavior 保持不变（end 为 nil）。

func InteractionWaitObserverFromContext(ctx context.Context) InteractionWaitObserver

type MCPServerConfig ¶ added in v0.1.22

type MCPServerConfig struct {
	Name        string
	Transport   string
	URL         string
	Command     string
	Args        []string
	Env         map[string]string
	Headers     map[string]string
	BearerToken string
}

MCPServerConfig describes one MCP endpoint exposed to an external Runtime.

type Message ¶

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message is a business-neutral conversation message supplied to a Runtime.

type MessageEndPayload ¶ added in v0.1.22

type MessageEndPayload struct {
	MessageID string `json:"message_id"`
	Content   string `json:"content"`
	Usage     *Usage `json:"usage,omitempty"`
}

MessageEndPayload carries the final assembled message.

type MessageStartPayload ¶ added in v0.1.22

type MessageStartPayload struct {
	MessageID string `json:"message_id"`
	Role      string `json:"role"`
}

MessageStartPayload carries the start of a message.

type MessageUpdatePayload ¶ added in v0.1.22

type MessageUpdatePayload struct {
	MessageID string `json:"message_id"`
	Role      string `json:"role"`
	Content   string `json:"content"`
}

MessageUpdatePayload carries a streaming text delta.

type ModelConfig ¶

type ModelConfig struct {
	Provider string
	Model    string
	APIKey   string
	BaseURL  string
	// Vision 表示该模型是否声明支持图片（多模态）输入。
	Vision bool
	// MaxTokens 默认最大输出 token 数；0 表示未配置，走 runtime/provider 默认。
	MaxTokens int
	// Temperature 默认采样温度；0 表示未配置，走 provider 默认。
	Temperature float64
	// TopP/FrequencyPenalty/PresencePenalty 采样参数。
	TopP             *float64
	FrequencyPenalty *float64
	PresencePenalty  *float64
	// ContextLimit/OutputLimit 模型上下文与单次输出上限；0 表示未设置，走默认。
	ContextLimit int
	OutputLimit  int
}

ModelConfig is the fully resolved model configuration for one execution.

type NodeEvent ¶ added in v0.1.22

type NodeEvent struct {
	ID          string            `json:"id"`
	ExecutionID string            `json:"execution_id"`
	TraceID     string            `json:"trace_id"`
	Type        NodeEventType     `json:"type"`
	OccurredAt  time.Time         `json:"occurred_at"`
	Payload     NodeEventPayload  `json:"payload,omitempty"`
	Metadata    NodeEventMetadata `json:"metadata,omitempty"`
}

NodeEvent is the stable runtime node event envelope emitted during execution. It describes execution facts, not business state.

func NewAgentEndEvent(sessionID string) NodeEvent

func NewAgentStartEvent(sessionID string) NodeEvent

func NewApprovalRequestedEvent(p ApprovalRequestedPayload) NodeEvent

func NewApprovalResolvedEvent(p ApprovalResolvedPayload) NodeEvent

func NewMessageEndEvent(content string, usage *Usage) NodeEvent

func NewMessageStartEvent(messageID, role string) NodeEvent

func NewMessageUpdateEvent(messageID, content string) NodeEvent

func NewPlanReadyEvent(path, displayPath, sessionID string) NodeEvent

func NewQuestionAnsweredEvent(p QuestionAnsweredPayload) NodeEvent

func NewQuestionAskedEvent(p QuestionAskedPayload) NodeEvent

func NewReasoningUpdateEvent(messageID, content string) NodeEvent

func NewTodoSnapshotEvent(items []RuntimeTodoItem) NodeEvent

func NewTodoUpdatedEvent(items []RuntimeTodoItem) NodeEvent

func NewToolExecutionEndErrorEvent(toolCallID, name, detail string, elapsedMS int64) NodeEvent

func NewToolExecutionEndEvent(toolCallID, name string, result json.RawMessage, elapsedMS int64) NodeEvent

func NewToolExecutionStartEvent(toolCallID, name string, arguments json.RawMessage) NodeEvent

func NewToolExecutionUpdateEvent(toolCallID, content string) NodeEvent

type NodeEventMetadata ¶ added in v0.1.22

type NodeEventMetadata map[string]string

NodeEventMetadata carries typed debug fields. It MUST NOT contain API Key, Authorization Header, or raw environment variables.

type NodeEventPayload ¶ added in v0.1.22

type NodeEventPayload interface {
	// contains filtered or unexported methods
}

NodeEventPayload is a sealed set of strongly-typed event payloads. Each concrete payload implements the marker method nodeEventPayload().

type NodeEventType ¶ added in v0.1.22

type NodeEventType string

NodeEventType identifies an observable runtime node event emitted during execution.

const (
	NodeEventAgentStart NodeEventType = "agent.start"
	NodeEventAgentEnd   NodeEventType = "agent.end"

	NodeEventMessageStart    NodeEventType = "message.start"
	NodeEventMessageUpdate   NodeEventType = "message.update"
	NodeEventReasoningUpdate NodeEventType = "reasoning.update"
	NodeEventMessageEnd      NodeEventType = "message.end"

	NodeEventToolExecutionStart  NodeEventType = "tool_execution.start"
	NodeEventToolExecutionUpdate NodeEventType = "tool_execution.update"
	NodeEventToolExecutionEnd    NodeEventType = "tool_execution.end"

	NodeEventTodoSnapshot NodeEventType = "todo.snapshot"
	NodeEventTodoUpdated  NodeEventType = "todo.updated"

	NodeEventApprovalRequested NodeEventType = "approval.requested"
	NodeEventApprovalResolved  NodeEventType = "approval.resolved"
	NodeEventQuestionAsked     NodeEventType = "question.asked"
	NodeEventQuestionAnswered  NodeEventType = "question.answered"

	NodeEventPlanReady NodeEventType = "plan.ready"
)

type NodeObserver ¶ added in v0.1.22

type NodeObserver interface {
	Observe(ctx context.Context, event NodeEvent) error
}

NodeObserver receives node events emitted during runtime execution. An observer that returns an error terminates the execution.

type NodeObserverFunc ¶ added in v0.1.22

type NodeObserverFunc func(ctx context.Context, event NodeEvent) error

NodeObserverFunc adapts a function to the NodeObserver interface.

func (f NodeObserverFunc) Observe(ctx context.Context, event NodeEvent) error

type PlanReadyPayload ¶ added in v0.1.22

type PlanReadyPayload struct {
	Path              string `json:"path"`
	DisplayPath       string `json:"display_path"`
	ProviderSessionID string `json:"provider_session_id,omitempty"`
}

PlanReadyPayload carries the safe path information for a detected plan file. Runtime emits only path info; Worker handles content reading, validation, and upload.

type ProviderSession ¶ added in v0.1.22

type ProviderSession struct {
	ID     string
	Resume bool
}

ProviderSession carries pre-resolved provider session information for resume.

type QuestionAnswer ¶

type QuestionAnswer struct {
	RequestID string
	Answers   [][]string
}

QuestionAnswer carries the user's response to a QuestionRequest.

type QuestionAnsweredPayload ¶ added in v0.1.22

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

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

type QuestionAskedPayload ¶ added in v0.1.22

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

QuestionAskedPayload describes a clarifying question from the runtime.

type QuestionItem ¶

type QuestionItem struct {
	Question    string
	Header      string
	Options     []QuestionOption
	MultiSelect bool
	Custom      bool
}

QuestionItem is a single question in a QuestionRequest.

type QuestionOption ¶

type QuestionOption struct {
	Label       string
	Description string
}

QuestionOption is one option for a QuestionItem.

type QuestionRequest ¶

type QuestionRequest struct {
	RequestID   string
	SessionKey  string
	Questions   []QuestionItem
	ToolCallID  string
	Description string
	Runtime     string
}

QuestionRequest carries one or more questions from a Runtime.

type QuestionResponder ¶ added in v0.1.22

type QuestionResponder interface {
	WriteAnswer(requestID string, answers [][]string) error
}

QuestionResponder writes question answers back to a provider runtime.

type ReasoningUpdatePayload ¶ added in v0.1.22

type ReasoningUpdatePayload struct {
	MessageID string `json:"message_id"`
	Content   string `json:"content"`
}

ReasoningUpdatePayload carries a reasoning/thinking text update.

type Registry ¶

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

Registry maps runtime kind names to Runtime implementations. It is populated at composition root and is read-only during execution.

func NewRegistry() *Registry

func (r *Registry) Names() []string

func (r *Registry) Register(name string, rt Runtime)

func (r *Registry) Resolve(kind string) (Runtime, error)

func (r *Registry) ResolveWithKind(kind string) (Runtime, string, error)

func (r *Registry) SetDefault(kind string)

type Runtime ¶

type Runtime interface {
	Name() string
	Execute(ctx context.Context, request ExecutionRequest, observer NodeObserver) (ExecutionResult, error)
}

Runtime executes a fully prepared request against a specific provider.

Runtime MUST NOT:

• Emit run.started, run.completed, run.failed, or run.cancelled events.
• Mutate ExecutionRequest.
• Access NATS, messaging, or Session persistence.

type RuntimeAdapterOptions ¶ added in v0.1.22

type RuntimeAdapterOptions struct {
	InteractionHandler InteractionHandler
	MCPServers         []MCPServerConfig
}

RuntimeAdapterOptions contains host-provided facilities shared by CLI adapters.

type RuntimeResolver ¶

type RuntimeResolver interface {
	Resolve(kind string) (Runtime, error)
}

RuntimeResolver maps a runtime kind string to a Runtime implementation.

type RuntimeTodoItem ¶ added in v0.1.22

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

RuntimeTodoItem describes a single runtime planning step.

type SerialObserver ¶ added in v0.1.22

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

SerialObserver wraps a NodeObserver to guarantee that all Observe calls are serialized. Concurrent calls from runtime activity (e.g. parallel tool completions) are enqueued and processed in order without blocking the runtime goroutine for longer than the serialization window.

An error from the underlying observer terminates execution — subsequent observes are dropped and the first error is returned.

func NewSerialObserver(inner NodeObserver) *SerialObserver

func (s *SerialObserver) Err() error

func (s *SerialObserver) Inner() NodeObserver

func (s *SerialObserver) Observe(ctx context.Context, event NodeEvent) error

type TodoReporter ¶ added in v0.1.22

type TodoReporter interface {
	Snapshot(ctx context.Context, items []RuntimeTodoItem) error
	Update(ctx context.Context, items []RuntimeTodoItem, merge bool) error
	List() []RuntimeTodoItem
}

TodoReporter exposes one execution's current runtime todo state to tools.

func TodoReporterFrom(ctx context.Context) (TodoReporter, bool)

type TodoSnapshotPayload ¶ added in v0.1.22

type TodoSnapshotPayload struct {
	Items []RuntimeTodoItem `json:"items"`
}

TodoSnapshotPayload carries a complete todo list snapshot.

type TodoUpdatedPayload ¶ added in v0.1.22

type TodoUpdatedPayload struct {
	Items []RuntimeTodoItem `json:"items"`
}

TodoUpdatedPayload carries an updated complete todo list.

type Tool ¶

type Tool interface {
	// Definition returns the tool metadata (name, description, parameters schema).
	Definition() ToolDefinition

	// Execute runs the tool with the given JSON input.
	Execute(ctx context.Context, input json.RawMessage) (ToolResult, error)
}

Tool is the contract for a callable tool within an agent Runtime. Implementations decode json.RawMessage into a typed request struct, execute the operation, and return a ToolResult.

type ToolCallRecord ¶

type ToolCallRecord struct {
	CallID string          `json:"call_id,omitempty"`
	Name   string          `json:"name,omitempty"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  string          `json:"error,omitempty"`
}

ToolCallRecord is a compact final tool call summary.

type ToolDefinition ¶

type ToolDefinition struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
}

ToolDefinition describes a tool exposed to a Runtime.

type ToolExecutionEndPayload ¶ added in v0.1.22

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

ToolExecutionEndPayload carries the result of a tool execution (success or failure).

type ToolExecutionStartPayload ¶ added in v0.1.22

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

ToolExecutionStartPayload carries the start of a tool execution.

type ToolExecutionUpdatePayload ¶ added in v0.1.22

type ToolExecutionUpdatePayload struct {
	ToolCallID string `json:"tool_call_id"`
	Content    string `json:"content"`
}

ToolExecutionUpdatePayload carries incremental tool execution content.

type ToolResult ¶

type ToolResult struct {
	Content string `json:"content,omitempty"`
	Error   string `json:"error,omitempty"`
	IsError bool   `json:"is_error"`
}

ToolResult is the result returned by a tool execution.

type Usage ¶

type Usage struct {
	TotalTokens       int `json:"total_tokens"`
	InputTokens       int `json:"input_tokens"`
	OutputTokens      int `json:"output_tokens"`
	CacheInputTokens  int `json:"cache_input_tokens"`
	CacheOutputTokens int `json:"cache_output_tokens"`
}

Usage describes model token usage when available.

func EnsureUsage(usage *Usage) *Usage