agent

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 Event ¶

type Event struct {
	ID        string          `json:"id,omitempty"`
	RunID     string          `json:"run_id,omitempty"`
	TraceID   string          `json:"trace_id,omitempty"`
	Seq       int64           `json:"seq,omitempty"`
	Type      EventType       `json:"type"`
	CreatedAt time.Time       `json:"created_at,omitempty"`
	Payload   json.RawMessage `json:"payload,omitempty"`
	Content   string          `json:"content,omitempty"`
}

Event is the stable runtime event envelope emitted during execution.

type EventSink ¶

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

EventSink receives observable events emitted during a run.

type EventType ¶

type EventType string

EventType identifies an observable runtime event emitted during execution.

type ExecutionMode ¶ added in v0.1.18

type ExecutionMode string

ExecutionMode describes how a runtime should handle one request.

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
	MaxSteps       int
	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
	Model        ModelConfig
	Tools        []Tool
	Policy       ExecutionPolicy
	Filesystem   FilesystemContext
}

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. Emit execution.started through the observer.
4. Call Runtime.Execute.
5. Handle cancellation propagation and observer errors.
6. Emit execution.completed / execution.failed / execution.cancelled.
7. Return ExecutionResult.

func NewExecutor(registry *Registry) *Executor

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

type FilesystemContext ¶

type FilesystemContext struct {
	WorkDir string
	RepoDir string
	TaskDir 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 Message ¶

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

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

type ModelConfig ¶

type ModelConfig struct {
	Provider string
	Model    string
	APIKey   string
	BaseURL  string
}

ModelConfig is the fully resolved model configuration for one execution.

type Observer ¶

type Observer interface {
	EventSink
}

Observer receives execution lifecycle events. An Observer that returns an error from any method terminates the execution.

type QuestionAnswer ¶

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

QuestionAnswer carries the user's response to a QuestionRequest.

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 Registry ¶

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

Registry maps runtime kind names to Runtime implementations. It is populated at composition root (cmd/leros/worker.go) 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) SetDefault(kind string)

type Runtime ¶

type Runtime interface {
	Name() string
	Execute(ctx context.Context, request ExecutionRequest, observer Observer) (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 RuntimeResolver ¶

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

RuntimeResolver maps a runtime kind string to a Runtime implementation.

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 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 {
	InputTokens  int `json:"input_tokens,omitempty"`
	OutputTokens int `json:"output_tokens,omitempty"`
	TotalTokens  int `json:"total_tokens,omitempty"`
}

Usage describes model token usage when available.