runtime

package
v0.3.9 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CapabilityOptions 

type CapabilityOptions struct {
	SkillsEnabled          bool
	SkillSources           []string
	SkillPromptBudgetBytes int
}

type Event added in v0.3.0 

type Event struct {
	Type         string                            `json:"type"`
	TraceID      TraceID                           `json:"trace_id,omitempty"`
	RunID        RunID                             `json:"run_id,omitempty"`
	ThreadID     ThreadID                          `json:"thread_id,omitempty"`
	TurnID       TurnID                            `json:"turn_id,omitempty"`
	Step         int                               `json:"step,omitempty"`
	Provider     string                            `json:"provider,omitempty"`
	Model        string                            `json:"model,omitempty"`
	Message      string                            `json:"message,omitempty"`
	Result       string                            `json:"result,omitempty"`
	Error        string                            `json:"error,omitempty"`
	ToolID       string                            `json:"tool_id,omitempty"`
	ToolName     string                            `json:"tool_name,omitempty"`
	ToolKind     string                            `json:"tool_kind,omitempty"`
	ArgsHash     string                            `json:"args_hash,omitempty"`
	DurationMS   int64                             `json:"duration_ms,omitempty"`
	FinishReason string                            `json:"finish_reason,omitempty"`
	Activity     *observation.ActivityPresentation `json:"activity,omitempty"`
	Metadata     map[string]any                    `json:"metadata,omitempty"`
	Timestamp    time.Time                         `json:"timestamp,omitempty"`
}

type EventSink added in v0.3.0 

type EventSink interface {
	EmitEvent(Event)
}

type Host added in v0.3.0 

type Host interface {
	StartThread(context.Context, StartThreadRequest) (ThreadSnapshot, error)
	ReadThread(context.Context, ThreadID) (ThreadSnapshot, error)
	RunTurn(context.Context, RunTurnRequest) (TurnResult, error)
	RetryTurn(context.Context, RetryTurnRequest) (TurnResult, error)
	DeleteThread(context.Context, ThreadID) error
	Close() error
}

func NewHost added in v0.3.0 

func NewHost(opts HostOptions) (Host, error)

type HostOptions added in v0.3.0 

type HostOptions struct {
	Config       config.Config
	Store        *Store
	Tools        *tools.Registry
	Approver     tools.Approver
	Sink         EventSink
	IDGenerator  func(string) string
	LoopLimits   LoopLimits
	Capabilities CapabilityOptions
}

type LoopLimits added in v0.3.0 

type LoopLimits struct {
	MaxEmptyProviderRetries int
	NoProgressLimit         int
	DuplicateToolLimit      int
	WallTime                time.Duration
}

type ModelEvent added in v0.3.1 

type ModelEvent struct {
	Type          ModelEventType   `json:"type"`
	Text          string           `json:"text,omitempty"`
	ToolCalls     []tools.ToolCall `json:"tool_calls,omitempty"`
	Reason        string           `json:"reason,omitempty"`
	Usage         ProviderUsage    `json:"usage,omitempty"`
	ResponseID    string           `json:"response_id,omitempty"`
	ResponseState *ModelState      `json:"response_state,omitempty"`
	Err           error            `json:"-"`
}

ModelEvent carries streamed model output.

type ModelEventType added in v0.3.1 

type ModelEventType string

ModelEventType is a streamed model event kind. 

const (
	ModelEventDelta     ModelEventType = "delta"
	ModelEventReasoning ModelEventType = "reasoning"
	ModelEventToolCalls ModelEventType = "tool_calls"
	ModelEventUsage     ModelEventType = "usage"
	ModelEventDone      ModelEventType = "done"
	ModelEventEmpty     ModelEventType = "empty"
	ModelEventTruncated ModelEventType = "truncated"
	ModelEventError     ModelEventType = "error"
)

type ModelGateway added in v0.3.1 

type ModelGateway interface {
	StreamModel(context.Context, ModelRequest) (<-chan ModelEvent, error)
}

ModelGateway lets a host supply model access while Floret still owns the agent loop, tool dispatch, context pressure, and runtime ledgers.

type ModelMessage added in v0.3.1 

type ModelMessage struct {
	Role       string `json:"role"`
	Content    string `json:"content,omitempty"`
	Reasoning  string `json:"reasoning,omitempty"`
	ToolCallID string `json:"tool_call_id,omitempty"`
	ToolName   string `json:"tool_name,omitempty"`
	ToolArgs   string `json:"tool_args,omitempty"`
}

ModelMessage is a provider-visible message generated by Floret for a ModelGateway request.

type ModelRequest added in v0.3.1 

type ModelRequest struct {
	RunID            RunID
	ThreadID         ThreadID
	TurnID           TurnID
	TraceID          TraceID
	PromptScopeID    PromptScopeID
	Step             int
	Provider         string
	Model            string
	Messages         []ModelMessage
	Tools            []tools.ToolDefinition
	MaxOutputTokens  int64
	DisableReasoning bool
	PreviousState    *ModelState
	Labels           RunLabels
}

ModelRequest is the host-safe model request shape passed to ModelGateway.

type ModelState added in v0.3.1 

type ModelState struct {
	Kind       string            `json:"kind,omitempty"`
	ID         string            `json:"id,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

ModelState is opaque model continuation state owned by Floret runtime data.

type ProjectedTurnOptions added in v0.3.1 

type ProjectedTurnOptions struct {
	Config       config.Config
	ModelGateway ModelGateway
	Store        *Store
	Tools        *tools.Registry
	Approver     tools.Approver
	Sink         EventSink
	LoopLimits   LoopLimits
	Capabilities CapabilityOptions
}

ProjectedTurnOptions configures one Floret-managed run over a host-owned transcript projection.

type ProjectedTurnRequest added in v0.3.1 

type ProjectedTurnRequest struct {
	RunID                 RunID
	ThreadID              ThreadID
	TurnID                TurnID
	TraceID               TraceID
	PromptScopeID         PromptScopeID
	History               []TranscriptMessage
	Labels                RunLabels
	PreviousProviderState *ModelState
	Completion            TurnCompletionPolicy
	Signals               TurnSignalSpec
	Limits                TurnLimits
}

ProjectedTurnRequest is the provider-visible transcript projection for one run. Execution identity fields are required and are not inferred from each other.

type ProjectedTurnResult added in v0.3.1 

type ProjectedTurnResult struct {
	RunID              RunID                        `json:"run_id,omitempty"`
	ThreadID           ThreadID                     `json:"thread_id,omitempty"`
	TurnID             TurnID                       `json:"turn_id,omitempty"`
	Status             TurnStatus                   `json:"status"`
	Output             string                       `json:"output,omitempty"`
	Error              string                       `json:"error,omitempty"`
	Metrics            RunMetrics                   `json:"metrics"`
	Transcript         []TranscriptMessage          `json:"transcript,omitempty"`
	CompletionReason   string                       `json:"completion_reason,omitempty"`
	ContinuationReason string                       `json:"continuation_reason,omitempty"`
	FinishReason       string                       `json:"finish_reason,omitempty"`
	RawFinishReason    string                       `json:"raw_finish_reason,omitempty"`
	FinishInferred     bool                         `json:"finish_inferred,omitempty"`
	Signal             *TurnSignal                  `json:"signal,omitempty"`
	ActivityTimeline   observation.ActivityTimeline `json:"activity_timeline"`
}

ProjectedTurnResult is the host-safe outcome of RunProjectedTurn.

func RunProjectedTurn added in v0.3.1 

func RunProjectedTurn(ctx context.Context, opts ProjectedTurnOptions, req ProjectedTurnRequest) (ProjectedTurnResult, error)

RunProjectedTurn executes one Floret-managed provider loop over a transcript supplied by the host.

Use this when the product owns durable conversation rows and Floret owns the turn execution, prompt scope, provider ledger, tool dispatch, and observable runtime events. Use Host for Floret-managed durable conversations.

type PromptScopeID added in v0.3.0 

type PromptScopeID string

type ProviderUsage added in v0.3.1 

type ProviderUsage struct {
	InputTokens       int64   `json:"input_tokens,omitempty"`
	OutputTokens      int64   `json:"output_tokens,omitempty"`
	ReasoningTokens   int64   `json:"reasoning_tokens,omitempty"`
	CacheReadTokens   int64   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens  int64   `json:"cache_write_tokens,omitempty"`
	TotalTokens       int64   `json:"total_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`
	Source            string  `json:"source,omitempty"`
	Available         bool    `json:"available,omitempty"`
	WindowInputTokens int64   `json:"window_input_tokens,omitempty"`
}

ProviderUsage is normalized provider token and cost usage.

type RetryTurnRequest added in v0.3.0 

type RetryTurnRequest struct {
	ThreadID ThreadID
	Reason   string
	Labels   RunLabels
}

type RunID added in v0.3.0 

type RunID string

type RunLabels added in v0.3.0 

type RunLabels struct {
	Correlation map[string]string
	Host        map[string]string
}

type RunMetrics added in v0.3.1 

type RunMetrics struct {
	ProviderUsage ProviderUsage `json:"provider_usage"`
	Steps         int           `json:"steps"`
	LLMRequests   int           `json:"llm_requests"`
	ToolCalls     int           `json:"tool_calls"`
	Compactions   int           `json:"compactions"`
	Retries       int           `json:"retries"`
	WallTimeMS    int64         `json:"wall_time_ms,omitempty"`
}

RunMetrics summarizes the observable work completed by a run.

type RunTurnRequest added in v0.3.0 

type RunTurnRequest struct {
	ThreadID ThreadID
	TurnID   TurnID
	Input    string
	Labels   RunLabels
}

type SignalDisposition added in v0.3.1 

type SignalDisposition string

SignalDisposition describes how a projected turn signal affects the run. 

const (
	// SignalContinue returns a provider-visible tool result and continues.
	SignalContinue SignalDisposition = "continue"
	// SignalWaiting pauses the run for host or user input.
	SignalWaiting SignalDisposition = "waiting"
	// SignalTerminal completes the run with the projected signal.
	SignalTerminal SignalDisposition = "terminal"
)

type StartThreadRequest added in v0.3.0 

type StartThreadRequest struct {
	ThreadID ThreadID
}

type Store added in v0.3.0 

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

func NewMemoryStore added in v0.3.0 

func NewMemoryStore() *Store

func OpenSQLiteStore added in v0.3.0 

func OpenSQLiteStore(path string) (*Store, error)

func (*Store) Close added in v0.3.0 

func (s *Store) Close() error

type ThreadID added in v0.3.0 

type ThreadID string

type ThreadMessage added in v0.3.0 

type ThreadMessage struct {
	Role      string    `json:"role"`
	Content   string    `json:"content"`
	TurnID    TurnID    `json:"turn_id,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type ThreadPhase added in v0.3.0 

type ThreadPhase string
const (
	ThreadPhaseIdle ThreadPhase = "idle"
	ThreadPhaseTurn ThreadPhase = "turn"
)

type ThreadSnapshot added in v0.3.0 

type ThreadSnapshot struct {
	ID               ThreadID        `json:"id"`
	Title            string          `json:"title,omitempty"`
	TitleStatus      string          `json:"title_status,omitempty"`
	TitleSource      string          `json:"title_source,omitempty"`
	TitleUpdatedAt   time.Time       `json:"title_updated_at,omitempty"`
	TitleError       string          `json:"title_error,omitempty"`
	CreatedAt        time.Time       `json:"created_at"`
	UpdatedAt        time.Time       `json:"updated_at"`
	Phase            ThreadPhase     `json:"phase"`
	Status           ThreadStatus    `json:"status"`
	LatestTurnID     TurnID          `json:"latest_turn_id,omitempty"`
	WaitingPrompt    string          `json:"waiting_prompt,omitempty"`
	Recoverable      bool            `json:"recoverable"`
	CanAppendMessage bool            `json:"can_append_message"`
	CanRetry         bool            `json:"can_retry"`
	Messages         []ThreadMessage `json:"messages"`
}

type ThreadStatus added in v0.3.0 

type ThreadStatus string
const (
	ThreadStatusIdle        ThreadStatus = "idle"
	ThreadStatusRunning     ThreadStatus = "running"
	ThreadStatusCompleted   ThreadStatus = "completed"
	ThreadStatusWaiting     ThreadStatus = "waiting"
	ThreadStatusFailed      ThreadStatus = "failed"
	ThreadStatusCancelled   ThreadStatus = "cancelled"
	ThreadStatusInterrupted ThreadStatus = "interrupted"
)

type TraceID added in v0.3.0 

type TraceID string

type TranscriptMessage added in v0.3.1 

type TranscriptMessage struct {
	Role       string `json:"role"`
	Content    string `json:"content,omitempty"`
	Reasoning  string `json:"reasoning,omitempty"`
	ToolCallID string `json:"tool_call_id,omitempty"`
	ToolName   string `json:"tool_name,omitempty"`
	ToolArgs   string `json:"tool_args,omitempty"`
}

TranscriptMessage is the small message shape accepted by RunProjectedTurn. Supported roles are user, assistant, and tool. System instructions belong in config.Config rather than host-projected transcript history.

type TurnCompletionPolicy added in v0.3.1 

type TurnCompletionPolicy string

TurnCompletionPolicy controls how the provider loop may finish. The zero value uses natural stops. 

const (
	// TurnCompletionNaturalStop lets the provider's natural stop finish the run.
	TurnCompletionNaturalStop TurnCompletionPolicy = "natural_stop"
	// TurnCompletionExplicitSignal requires a projected turn signal to finish or
	// pause the run.
	TurnCompletionExplicitSignal TurnCompletionPolicy = "explicit_signal"
)

type TurnID added in v0.3.0 

type TurnID string

type TurnLimits added in v0.3.1 

type TurnLimits struct {
	MaxTotalTokens           int64
	MaxCostUSD               float64
	MaxToolCalls             int
	MaxLengthContinuations   int
	MaxStopHookContinuations int
}

TurnLimits contains per-run budget and continuation caps.

type TurnResult added in v0.3.0 

type TurnResult struct {
	ID                 TurnID            `json:"id"`
	Status             TurnStatus        `json:"status"`
	Output             string            `json:"output,omitempty"`
	Error              string            `json:"error,omitempty"`
	Diagnostics        map[string]string `json:"diagnostics,omitempty"`
	CompletionReason   string            `json:"completion_reason,omitempty"`
	ContinuationReason string            `json:"continuation_reason,omitempty"`
	FinishReason       string            `json:"finish_reason,omitempty"`
	RawFinishReason    string            `json:"raw_finish_reason,omitempty"`
	FinishInferred     bool              `json:"finish_inferred,omitempty"`
}

type TurnSignal added in v0.3.1 

type TurnSignal struct {
	Disposition SignalDisposition                 `json:"disposition"`
	Name        string                            `json:"name"`
	CallID      string                            `json:"call_id,omitempty"`
	Payload     map[string]any                    `json:"payload,omitempty"`
	Activity    *observation.ActivityPresentation `json:"activity,omitempty"`
	OutputText  string                            `json:"output_text,omitempty"`
	ArgsHash    string                            `json:"args_hash,omitempty"`
	Labels      map[string]string                 `json:"labels,omitempty"`
}

TurnSignal is a host-safe projection of a signal tool call.

type TurnSignalSpec added in v0.3.1 

type TurnSignalSpec struct {
	Definitions []tools.ToolDefinition
	Project     func(tools.ToolCall) (TurnSignal, bool, error)
}

TurnSignalSpec lets a host declare provider-visible signal tools without importing Floret implementation packages.

type TurnStatus added in v0.3.0 

type TurnStatus string
const (
	TurnStatusCompleted TurnStatus = "completed"
	TurnStatusWaiting   TurnStatus = "waiting"
	TurnStatusFailed    TurnStatus = "failed"
	TurnStatusCancelled TurnStatus = "cancelled"
)

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.