runtime

package
v0.3.47 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CoreControlAskUser      = tools.ControlAskUser
	CoreControlTaskComplete = tools.ControlTaskComplete
)
View Source 
const (
	ReasoningLevelDefault = config.ReasoningLevelDefault
	ReasoningLevelOff     = config.ReasoningLevelOff
	ReasoningLevelMinimal = config.ReasoningLevelMinimal
	ReasoningLevelLow     = config.ReasoningLevelLow
	ReasoningLevelMedium  = config.ReasoningLevelMedium
	ReasoningLevelHigh    = config.ReasoningLevelHigh
	ReasoningLevelXHigh   = config.ReasoningLevelXHigh
	ReasoningLevelMax     = config.ReasoningLevelMax
)

Variables

This section is empty.

Functions

func CoreControlDefinitions added in v0.3.10 

func CoreControlDefinitions(includeTaskComplete bool) []tools.ToolDefinition

CoreControlDefinitions returns product-neutral control signal tools for hosts that want Floret to own common ask-user/task-complete schema validation.

func ManualCompactionOperationID added in v0.3.33 

func ManualCompactionOperationID(runID RunID, step int, requestID string) string

ManualCompactionOperationID returns the Floret operation identity that links the start, debug, complete, and failed observations for a projected manual compaction at the given provider-loop step.

func ProviderSafeCoreControlText added in v0.3.10 

func ProviderSafeCoreControlText(signal TurnSignal) string

ProviderSafeCoreControlText returns provider-visible transcript text for product-neutral core control signals.

Types

type ArtifactRef added in v0.3.21 

type ArtifactRef struct {
	ID        string `json:"id,omitempty"`
	SafeLabel string `json:"safe_label,omitempty"`
	URL       string `json:"url,omitempty"`
	Kind      string `json:"kind,omitempty"`
	MIME      string `json:"mime,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
	SHA256    string `json:"sha256,omitempty"`
}

type CapabilityOptions 

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

type CloseSubAgentRequest added in v0.3.17 

type CloseSubAgentRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	Reason         string
}

type CloseSubAgentsRequest added in v0.3.45 

type CloseSubAgentsRequest struct {
	ParentThreadID ThreadID
	Reason         string
}

type CloseSubAgentsResult added in v0.3.45 

type CloseSubAgentsResult struct {
	Snapshots []SubAgentSnapshot `json:"snapshots"`
	Closed    int                `json:"closed,omitempty"`
}

type CompactThreadRequest added in v0.3.37 

type CompactThreadRequest struct {
	ThreadID              ThreadID
	RequestID             string
	Source                string
	Labels                RunLabels
	PreviousProviderState *ModelState
	Limits                TurnLimits
	Reasoning             ReasoningSelection
}

type CompactThreadResult added in v0.3.37 

type CompactThreadResult struct {
	ThreadID         ThreadID                     `json:"thread_id,omitempty"`
	Status           string                       `json:"status"`
	Error            string                       `json:"error,omitempty"`
	Diagnostics      map[string]string            `json:"diagnostics,omitempty"`
	Metrics          RunMetrics                   `json:"metrics"`
	ProviderState    *ModelState                  `json:"provider_state,omitempty"`
	ActivityTimeline observation.ActivityTimeline `json:"activity_timeline"`
}

type EnsureThreadRequest added in v0.3.44 

type EnsureThreadRequest struct {
	ThreadID ThreadID
}

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"`
	Stream          *StreamObservation                `json:"stream,omitempty"`
	Committed       *ThreadDetailEvent                `json:"committed,omitempty"`
	ContextStatus   *observation.ContextStatus        `json:"context_status,omitempty"`
	Compaction      *observation.CompactionEvent      `json:"compaction,omitempty"`
	CompactionDebug *observation.CompactionDebugEvent `json:"compaction_debug,omitempty"`
	Sources         []SourceRef                       `json:"sources,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)
	EnsureThread(context.Context, EnsureThreadRequest) (ThreadSummary, error)
	ReadThread(context.Context, ThreadID) (ThreadSnapshot, error)
	ListThreadDetailEvents(context.Context, ListThreadDetailEventsRequest) (ThreadDetailEvents, error)
	ListPendingApprovals(context.Context, ListPendingApprovalsRequest) (PendingApprovals, error)
	RunTurn(context.Context, RunTurnRequest) (TurnResult, error)
	RetryTurn(context.Context, RetryTurnRequest) (TurnResult, error)
	CompactThread(context.Context, CompactThreadRequest) (CompactThreadResult, error)
	CompletePendingTool(context.Context, PendingToolCompletionRequest) (TurnResult, error)
	SpawnSubAgent(context.Context, SpawnSubAgentRequest) (SubAgentSnapshot, error)
	SendSubAgentInput(context.Context, SendSubAgentInputRequest) (SubAgentSnapshot, error)
	WaitSubAgents(context.Context, WaitSubAgentsRequest) (WaitSubAgentsResult, error)
	ListSubAgents(context.Context, ThreadID) ([]SubAgentSnapshot, error)
	CloseSubAgent(context.Context, CloseSubAgentRequest) (SubAgentSnapshot, error)
	CloseSubAgents(context.Context, CloseSubAgentsRequest) (CloseSubAgentsResult, error)
	ListSubAgentActivityTimeline(context.Context, ListSubAgentActivityTimelineRequest) (SubAgentActivityTimelineResult, error)
	ReadSubAgentDetail(context.Context, ReadSubAgentDetailRequest) (SubAgentDetail, error)
	ListSubAgentDetailEvents(context.Context, ListSubAgentDetailEventsRequest) (SubAgentDetailEvents, 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
	ModelGateway        ModelGateway
	Store               *Store
	Tools               *tools.Registry
	Approver            tools.Approver
	Sink                EventSink
	ToolSurfaceProvider ToolSurfaceProvider
	IDGenerator         func(string) string
	LoopLimits          LoopLimits
	SubAgentRunTimeout  time.Duration
	Capabilities        CapabilityOptions
}

type HostedToolDefinition added in v0.3.40 

type HostedToolDefinition struct {
	Name        string         `json:"name"`
	Type        string         `json:"type"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Options     map[string]any `json:"options,omitempty"`
}

type ListPendingApprovalsRequest added in v0.3.46 

type ListPendingApprovalsRequest struct {
	ThreadID ThreadID
}

type ListSubAgentActivityTimelineRequest added in v0.3.44 

type ListSubAgentActivityTimelineRequest struct {
	ParentThreadID ThreadID
	Meta           observation.ActivityRunMeta
}

type ListSubAgentDetailEventsRequest added in v0.3.21 

type ListSubAgentDetailEventsRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	AfterOrdinal   int64
	Limit          int
	IncludeRaw     bool
}

type ListThreadDetailEventsRequest added in v0.3.42 

type ListThreadDetailEventsRequest struct {
	ThreadID     ThreadID
	AfterOrdinal int64
	Limit        int
	IncludeRaw   bool
}

type LoopLimits added in v0.3.0 

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

type ManualCompactionPollRequest added in v0.3.27 

type ManualCompactionPollRequest struct {
	RunID         RunID         `json:"run_id,omitempty"`
	ThreadID      ThreadID      `json:"thread_id,omitempty"`
	TurnID        TurnID        `json:"turn_id,omitempty"`
	TraceID       TraceID       `json:"trace_id,omitempty"`
	PromptScopeID PromptScopeID `json:"prompt_scope_id,omitempty"`
	Step          int           `json:"step,omitempty"`
}

type ManualCompactionRequest added in v0.3.27 

type ManualCompactionRequest struct {
	RequestID   string    `json:"request_id"`
	Source      string    `json:"source,omitempty"`
	RequestedAt time.Time `json:"requested_at,omitempty"`
}

type ManualCompactionSource added in v0.3.27 

type ManualCompactionSource interface {
	PollManualCompaction(context.Context, ManualCompactionPollRequest) (ManualCompactionRequest, bool, error)
}

type ModelEvent added in v0.3.1 

type ModelEvent struct {
	Type           ModelEventType       `json:"type"`
	Text           string               `json:"text,omitempty"`
	ToolCallStream *ModelToolCallStream `json:"tool_call_stream,omitempty"`
	ToolCalls      []tools.ToolCall     `json:"tool_calls,omitempty"`
	Sources        []SourceRef          `json:"sources,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"
	ModelEventToolCallStart ModelEventType = "tool_call_start"
	ModelEventToolCallDelta ModelEventType = "tool_call_delta"
	ModelEventToolCallEnd   ModelEventType = "tool_call_end"
	ModelEventToolCalls     ModelEventType = "tool_calls"
	ModelEventUsage         ModelEventType = "usage"
	ModelEventSources       ModelEventType = "sources"
	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
	HostedTools     []HostedToolDefinition
	MaxOutputTokens int64
	Reasoning       ReasoningSelection
	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 provider continuation state. Floret carries it through the run lifecycle and returns the latest state; hosts and model gateways own provider-specific interpretation and cross-turn persistence.

type ModelToolCallStream added in v0.3.16 

type ModelToolCallStream struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

ModelToolCallStream identifies a tool call while the model is still generating it. The final executable tool calls are delivered separately by ModelEventToolCalls.

type PendingApproval added in v0.3.46 

type PendingApproval struct {
	ApprovalID  string                    `json:"approval_id,omitempty"`
	ToolCallID  string                    `json:"tool_call_id,omitempty"`
	ToolName    string                    `json:"tool_name,omitempty"`
	ToolKind    string                    `json:"tool_kind,omitempty"`
	RunID       RunID                     `json:"run_id,omitempty"`
	ThreadID    ThreadID                  `json:"thread_id,omitempty"`
	TurnID      TurnID                    `json:"turn_id,omitempty"`
	Step        int                       `json:"step,omitempty"`
	State       string                    `json:"state,omitempty"`
	Revision    int64                     `json:"revision,omitempty"`
	Epoch       int64                     `json:"epoch,omitempty"`
	RequestedAt time.Time                 `json:"requested_at,omitempty"`
	ResolvedAt  time.Time                 `json:"resolved_at,omitempty"`
	ArgsHash    string                    `json:"args_hash,omitempty"`
	Resources   []PendingApprovalResource `json:"resources,omitempty"`
	Effects     []string                  `json:"effects,omitempty"`
	Labels      map[string]string         `json:"labels,omitempty"`
	HostContext map[string]string         `json:"host_context,omitempty"`
	ReadOnly    bool                      `json:"read_only,omitempty"`
	Destructive bool                      `json:"destructive,omitempty"`
	OpenWorld   bool                      `json:"open_world,omitempty"`
	Reason      string                    `json:"reason,omitempty"`
}

type PendingApprovalResource added in v0.3.46 

type PendingApprovalResource struct {
	Kind  string `json:"kind,omitempty"`
	Value string `json:"value,omitempty"`
}

type PendingApprovals added in v0.3.46 

type PendingApprovals struct {
	ThreadID    ThreadID          `json:"thread_id"`
	Approvals   []PendingApproval `json:"approvals"`
	GeneratedAt time.Time         `json:"generated_at"`
}

type PendingToolCompletionRequest added in v0.3.10 

type PendingToolCompletionRequest struct {
	ThreadID   ThreadID
	TurnID     TurnID
	RunID      RunID
	ToolCallID string
	ToolName   string
	Handle     string
	Status     PendingToolCompletionStatus
	Summary    string
	Output     string
	Labels     RunLabels
}

PendingToolCompletionRequest asks Floret to append a host-authored follow-up turn for work whose lifecycle was owned outside Floret.

type PendingToolCompletionStatus added in v0.3.10 

type PendingToolCompletionStatus string

PendingToolCompletionStatus describes the observed outcome of host-owned work that was previously exposed to the agent as a pending tool result. 

const (
	PendingToolCompletionCompleted PendingToolCompletionStatus = "completed"
	PendingToolCompletionFailed    PendingToolCompletionStatus = "failed"
	PendingToolCompletionCanceled  PendingToolCompletionStatus = "canceled"
)

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 ReadSubAgentDetailRequest added in v0.3.21 

type ReadSubAgentDetailRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	AfterOrdinal   int64
	Limit          int
	IncludeRaw     bool
}

type ReasoningBudget added in v0.3.19 

type ReasoningBudget = config.ReasoningBudget

type ReasoningCapability added in v0.3.19 

type ReasoningCapability = config.ReasoningCapability

type ReasoningLevel added in v0.3.19 

type ReasoningLevel = config.ReasoningLevel

type ReasoningSelection added in v0.3.19 

type ReasoningSelection = config.ReasoningSelection

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
	PreviousProviderState *ModelState
	Completion            TurnCompletionPolicy
	Signals               TurnSignalSpec
	Limits                TurnLimits
	Reasoning             ReasoningSelection
	ManualCompactions     ManualCompactionSource
	ToolSurfaceProvider   ToolSurfaceProvider
}

type SendSubAgentInputRequest added in v0.3.17 

type SendSubAgentInputRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	Message        string
	Interrupt      bool
	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 SourceRef added in v0.3.13 

type SourceRef struct {
	Title string `json:"title,omitempty"`
	URL   string `json:"url,omitempty"`
}

type SpawnSubAgentRequest added in v0.3.17 

type SpawnSubAgentRequest struct {
	ParentThreadID ThreadID
	ParentTurnID   TurnID
	ThreadID       ThreadID
	TaskName       string
	Message        string
	HostProfileRef string
	ForkMode       SubAgentForkMode
	Labels         RunLabels
}

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 StreamObservation added in v0.3.10 

type StreamObservation struct {
	Type            StreamObservationType `json:"type"`
	Text            string                `json:"text,omitempty"`
	ToolCallStream  *ModelToolCallStream  `json:"tool_call_stream,omitempty"`
	Reason          string                `json:"reason,omitempty"`
	FinishReason    string                `json:"finish_reason,omitempty"`
	RawFinishReason string                `json:"raw_finish_reason,omitempty"`
	FinishInferred  bool                  `json:"finish_inferred,omitempty"`
	Attempt         int                   `json:"attempt,omitempty"`
	Labels          RunLabels             `json:"labels,omitempty"`
}

StreamObservation is a provider-neutral, engine-confirmed streaming fact for hosts that render live assistant output from Floret runtime events.

type StreamObservationType added in v0.3.10 

type StreamObservationType string
const (
	StreamObservationAssistantDelta   StreamObservationType = "assistant_delta"
	StreamObservationReasoningDelta   StreamObservationType = "reasoning_delta"
	StreamObservationToolCallStart    StreamObservationType = "tool_call_start"
	StreamObservationToolCallDelta    StreamObservationType = "tool_call_delta"
	StreamObservationToolCallEnd      StreamObservationType = "tool_call_end"
	StreamObservationModelRetry       StreamObservationType = "model_retry"
	StreamObservationModelStreamDone  StreamObservationType = "model_stream_done"
	StreamObservationModelStreamAbort StreamObservationType = "model_stream_abort"
)

type SubAgentActivityTimelineResult added in v0.3.44 

type SubAgentActivityTimelineResult struct {
	Timeline    observation.ActivityTimeline `json:"activity_timeline"`
	GeneratedAt time.Time                    `json:"generated_at"`
}

type SubAgentDetail added in v0.3.21 

type SubAgentDetail struct {
	Snapshot     SubAgentSnapshot      `json:"snapshot"`
	Events       []SubAgentDetailEvent `json:"events"`
	NextOrdinal  int64                 `json:"next_ordinal,omitempty"`
	HasMore      bool                  `json:"has_more,omitempty"`
	RetainedFrom int64                 `json:"retained_from,omitempty"`
	GeneratedAt  time.Time             `json:"generated_at"`
}

type SubAgentDetailApproval added in v0.3.21 

type SubAgentDetailApproval struct {
	State    string            `json:"state,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"`
	Reason   string            `json:"reason,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type SubAgentDetailCompaction added in v0.3.21 

type SubAgentDetailCompaction struct {
	Trigger             string            `json:"trigger,omitempty"`
	Reason              string            `json:"reason,omitempty"`
	Phase               string            `json:"phase,omitempty"`
	TokensBefore        int64             `json:"tokens_before,omitempty"`
	TokensAfterEstimate int64             `json:"tokens_after_estimate,omitempty"`
	Metadata            map[string]string `json:"metadata,omitempty"`
}

type SubAgentDetailEvent added in v0.3.21 

type SubAgentDetailEvent struct {
	ID        string                  `json:"id"`
	Ordinal   int64                   `json:"ordinal"`
	ParentID  string                  `json:"parent_id,omitempty"`
	ThreadID  ThreadID                `json:"thread_id"`
	TurnID    TurnID                  `json:"turn_id,omitempty"`
	Kind      SubAgentDetailEventKind `json:"kind"`
	Type      string                  `json:"type,omitempty"`
	CreatedAt time.Time               `json:"created_at"`

	Message    *SubAgentDetailMessage    `json:"message,omitempty"`
	ToolCall   *SubAgentDetailToolCall   `json:"tool_call,omitempty"`
	ToolResult *SubAgentDetailToolResult `json:"tool_result,omitempty"`
	Approval   *SubAgentDetailApproval   `json:"approval,omitempty"`
	TurnMarker *SubAgentDetailTurnMarker `json:"turn_marker,omitempty"`
	Compaction *SubAgentDetailCompaction `json:"compaction,omitempty"`
	Error      string                    `json:"error,omitempty"`
	Metadata   map[string]string         `json:"metadata,omitempty"`

	ActivityTimeline *observation.ActivityTimeline `json:"activity_timeline,omitempty"`
}

type SubAgentDetailEventKind added in v0.3.21 

type SubAgentDetailEventKind string
const (
	SubAgentDetailEventUserMessage      SubAgentDetailEventKind = "user_message"
	SubAgentDetailEventAssistantMessage SubAgentDetailEventKind = "assistant_message"
	SubAgentDetailEventToolCall         SubAgentDetailEventKind = "tool_call"
	SubAgentDetailEventToolResult       SubAgentDetailEventKind = "tool_result"
	SubAgentDetailEventTurnMarker       SubAgentDetailEventKind = "turn_marker"
	SubAgentDetailEventCompaction       SubAgentDetailEventKind = "compaction"
	SubAgentDetailEventError            SubAgentDetailEventKind = "error"
	SubAgentDetailEventApproval         SubAgentDetailEventKind = "approval"
	SubAgentDetailEventInput            SubAgentDetailEventKind = "input"
	SubAgentDetailEventCustom           SubAgentDetailEventKind = "custom"
)

type SubAgentDetailEvents added in v0.3.21 

type SubAgentDetailEvents struct {
	Events       []SubAgentDetailEvent `json:"events"`
	NextOrdinal  int64                 `json:"next_ordinal,omitempty"`
	HasMore      bool                  `json:"has_more,omitempty"`
	RetainedFrom int64                 `json:"retained_from,omitempty"`
	GeneratedAt  time.Time             `json:"generated_at"`
}

type SubAgentDetailMessage added in v0.3.21 

type SubAgentDetailMessage struct {
	Role      string `json:"role,omitempty"`
	Preview   string `json:"preview,omitempty"`
	Content   string `json:"content,omitempty"`
	Reasoning string `json:"reasoning,omitempty"`
}

type SubAgentDetailToolCall added in v0.3.21 

type SubAgentDetailToolCall struct {
	ID          string `json:"id,omitempty"`
	Name        string `json:"name,omitempty"`
	ArgsPreview string `json:"args_preview,omitempty"`
	ArgsJSON    string `json:"args_json,omitempty"`
	ArgsHash    string `json:"args_hash,omitempty"`
}

type SubAgentDetailToolResult added in v0.3.21 

type SubAgentDetailToolResult struct {
	CallID        string       `json:"call_id,omitempty"`
	ToolName      string       `json:"tool_name,omitempty"`
	Status        string       `json:"status,omitempty"`
	Preview       string       `json:"preview,omitempty"`
	Content       string       `json:"content,omitempty"`
	Truncated     bool         `json:"truncated,omitempty"`
	OriginalBytes int          `json:"original_bytes,omitempty"`
	VisibleBytes  int          `json:"visible_bytes,omitempty"`
	OriginalLines int          `json:"original_lines,omitempty"`
	VisibleLines  int          `json:"visible_lines,omitempty"`
	Strategy      string       `json:"strategy,omitempty"`
	ContentSHA256 string       `json:"content_sha256,omitempty"`
	FullOutput    *ArtifactRef `json:"full_output,omitempty"`
}

type SubAgentDetailTurnMarker added in v0.3.21 

type SubAgentDetailTurnMarker struct {
	Status   string            `json:"status,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type SubAgentForkMode added in v0.3.17 

type SubAgentForkMode string
const (
	SubAgentForkNone     SubAgentForkMode = "none"
	SubAgentForkFullPath SubAgentForkMode = "full_path"
)

type SubAgentSnapshot added in v0.3.17 

type SubAgentSnapshot struct {
	ThreadID       ThreadID         `json:"thread_id"`
	Path           string           `json:"path"`
	TaskName       string           `json:"task_name"`
	ParentThreadID ThreadID         `json:"parent_thread_id"`
	ParentTurnID   TurnID           `json:"parent_turn_id,omitempty"`
	HostProfileRef string           `json:"host_profile_ref,omitempty"`
	ForkMode       SubAgentForkMode `json:"fork_mode,omitempty"`
	Status         SubAgentStatus   `json:"status"`
	LatestTurnID   TurnID           `json:"latest_turn_id,omitempty"`
	LastMessage    string           `json:"last_message,omitempty"`
	WaitingPrompt  string           `json:"waiting_prompt,omitempty"`
	QueuedInputs   int              `json:"queued_inputs,omitempty"`
	CreatedAt      time.Time        `json:"created_at"`
	UpdatedAt      time.Time        `json:"updated_at"`
	Closed         bool             `json:"closed,omitempty"`
	CanSendInput   bool             `json:"can_send_input"`
	CanInterrupt   bool             `json:"can_interrupt"`
	CanClose       bool             `json:"can_close"`
}

type SubAgentStatus added in v0.3.17 

type SubAgentStatus string
const (
	SubAgentStatusIdle        SubAgentStatus = "idle"
	SubAgentStatusRunning     SubAgentStatus = "running"
	SubAgentStatusWaiting     SubAgentStatus = "waiting"
	SubAgentStatusCompleted   SubAgentStatus = "completed"
	SubAgentStatusFailed      SubAgentStatus = "failed"
	SubAgentStatusCancelled   SubAgentStatus = "cancelled"
	SubAgentStatusInterrupted SubAgentStatus = "interrupted"
	SubAgentStatusClosed      SubAgentStatus = "closed"
)

type ThreadDetailApproval added in v0.3.42 

type ThreadDetailApproval struct {
	State    string            `json:"state,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"`
	Reason   string            `json:"reason,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type ThreadDetailCompaction added in v0.3.42 

type ThreadDetailCompaction struct {
	CompactionID            string            `json:"compaction_id,omitempty"`
	PreviousCompactionID    string            `json:"previous_compaction_id,omitempty"`
	CompactedThroughEntryID string            `json:"compacted_through_entry_id,omitempty"`
	SummarySchemaVersion    string            `json:"summary_schema_version,omitempty"`
	CompactionGeneration    int               `json:"compaction_generation,omitempty"`
	CompactionWindowID      string            `json:"compaction_window_id,omitempty"`
	FirstKeptEntryID        string            `json:"first_kept_entry_id,omitempty"`
	KeptUserEntryIDs        []string          `json:"kept_user_entry_ids,omitempty"`
	Summary                 string            `json:"summary,omitempty"`
	Trigger                 string            `json:"trigger,omitempty"`
	Reason                  string            `json:"reason,omitempty"`
	Phase                   string            `json:"phase,omitempty"`
	TokensBefore            int64             `json:"tokens_before,omitempty"`
	TokensAfterEstimate     int64             `json:"tokens_after_estimate,omitempty"`
	Metadata                map[string]string `json:"metadata,omitempty"`
}

type ThreadDetailEvent added in v0.3.42 

type ThreadDetailEvent struct {
	ID        string                `json:"id"`
	Ordinal   int64                 `json:"ordinal"`
	ParentID  string                `json:"parent_id,omitempty"`
	ThreadID  ThreadID              `json:"thread_id"`
	TurnID    TurnID                `json:"turn_id,omitempty"`
	Kind      ThreadDetailEventKind `json:"kind"`
	Type      string                `json:"type,omitempty"`
	CreatedAt time.Time             `json:"created_at"`

	Message    *ThreadDetailMessage    `json:"message,omitempty"`
	ToolCall   *ThreadDetailToolCall   `json:"tool_call,omitempty"`
	ToolResult *ThreadDetailToolResult `json:"tool_result,omitempty"`
	Approval   *ThreadDetailApproval   `json:"approval,omitempty"`
	TurnMarker *ThreadDetailTurnMarker `json:"turn_marker,omitempty"`
	Compaction *ThreadDetailCompaction `json:"compaction,omitempty"`
	Error      string                  `json:"error,omitempty"`
	Metadata   map[string]string       `json:"metadata,omitempty"`

	ActivityTimeline *observation.ActivityTimeline `json:"activity_timeline,omitempty"`
}

type ThreadDetailEventKind added in v0.3.42 

type ThreadDetailEventKind string
const (
	ThreadDetailEventUserMessage      ThreadDetailEventKind = "user_message"
	ThreadDetailEventAssistantMessage ThreadDetailEventKind = "assistant_message"
	ThreadDetailEventToolCall         ThreadDetailEventKind = "tool_call"
	ThreadDetailEventToolResult       ThreadDetailEventKind = "tool_result"
	ThreadDetailEventTurnMarker       ThreadDetailEventKind = "turn_marker"
	ThreadDetailEventCompaction       ThreadDetailEventKind = "compaction"
	ThreadDetailEventError            ThreadDetailEventKind = "error"
	ThreadDetailEventApproval         ThreadDetailEventKind = "approval"
	ThreadDetailEventInput            ThreadDetailEventKind = "input"
	ThreadDetailEventCustom           ThreadDetailEventKind = "custom"
)

type ThreadDetailEvents added in v0.3.42 

type ThreadDetailEvents struct {
	Events       []ThreadDetailEvent `json:"events"`
	NextOrdinal  int64               `json:"next_ordinal,omitempty"`
	HasMore      bool                `json:"has_more,omitempty"`
	RetainedFrom int64               `json:"retained_from,omitempty"`
	GeneratedAt  time.Time           `json:"generated_at"`
}

type ThreadDetailMessage added in v0.3.42 

type ThreadDetailMessage struct {
	Role      string `json:"role,omitempty"`
	Preview   string `json:"preview,omitempty"`
	Content   string `json:"content,omitempty"`
	Reasoning string `json:"reasoning,omitempty"`
}

type ThreadDetailToolCall added in v0.3.42 

type ThreadDetailToolCall struct {
	ID          string `json:"id,omitempty"`
	Name        string `json:"name,omitempty"`
	ArgsPreview string `json:"args_preview,omitempty"`
	ArgsJSON    string `json:"args_json,omitempty"`
	ArgsHash    string `json:"args_hash,omitempty"`
}

type ThreadDetailToolResult added in v0.3.42 

type ThreadDetailToolResult struct {
	CallID        string       `json:"call_id,omitempty"`
	ToolName      string       `json:"tool_name,omitempty"`
	Status        string       `json:"status,omitempty"`
	Preview       string       `json:"preview,omitempty"`
	Content       string       `json:"content,omitempty"`
	Truncated     bool         `json:"truncated,omitempty"`
	OriginalBytes int          `json:"original_bytes,omitempty"`
	VisibleBytes  int          `json:"visible_bytes,omitempty"`
	OriginalLines int          `json:"original_lines,omitempty"`
	VisibleLines  int          `json:"visible_lines,omitempty"`
	Strategy      string       `json:"strategy,omitempty"`
	ContentSHA256 string       `json:"content_sha256,omitempty"`
	FullOutput    *ArtifactRef `json:"full_output,omitempty"`
}

type ThreadDetailTurnMarker added in v0.3.42 

type ThreadDetailTurnMarker struct {
	Status   string            `json:"status,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

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 ThreadSummary added in v0.3.44 

type ThreadSummary 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"`
}

type ToolSurface added in v0.3.40 

type ToolSurface struct {
	Tools                 *tools.Registry
	ToolDefinitions       []tools.ToolDefinition
	HostedToolDefinitions []HostedToolDefinition
	SystemPrompt          string
	HostContext           map[string]string
	Epoch                 string
	Reason                string
}

ToolSurface is the host-supplied tool view for the current run phase. It is product-neutral: hosts own policy names and may project them into tools, prompt text, or host context without Floret interpreting them.

type ToolSurfaceProvider added in v0.3.40 

type ToolSurfaceProvider func(context.Context, ToolSurfaceRequest) (ToolSurface, error)

type ToolSurfaceRequest added in v0.3.40 

type ToolSurfaceRequest struct {
	RunID         RunID
	ThreadID      ThreadID
	TurnID        TurnID
	TraceID       TraceID
	PromptScopeID PromptScopeID
	Step          int
	Phase         string
	Labels        RunLabels
	HostContext   map[string]string
}

ToolSurfaceRequest identifies the run phase asking for the current host tool surface. Hosts may use it to refresh tool visibility, hosted tools, prompt instructions, and host context between provider requests and tool dispatch.

type TraceID added in v0.3.0 

type TraceID string

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"`
	Metrics            RunMetrics                   `json:"metrics"`
	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"`
	ProviderState      *ModelState                  `json:"provider_state,omitempty"`
	Signal             *TurnSignal                  `json:"signal,omitempty"`
	ActivityTimeline   observation.ActivityTimeline `json:"activity_timeline"`
	PendingApprovals   []PendingApproval            `json:"pending_approvals,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.

func ProjectCoreControlSignal added in v0.3.10 

func ProjectCoreControlSignal(call tools.ToolCall) (TurnSignal, bool, error)

ProjectCoreControlSignal projects ask_user/task_complete tool calls into Floret control signals. Host-specific modes and UI payloads stay outside this helper.

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"
)

type WaitSubAgentsRequest added in v0.3.17 

type WaitSubAgentsRequest struct {
	ParentThreadID ThreadID
	ChildThreadIDs []ThreadID
	Timeout        time.Duration
}

type WaitSubAgentsResult added in v0.3.17 

type WaitSubAgentsResult struct {
	Snapshots []SubAgentSnapshot `json:"snapshots"`
	TimedOut  bool               `json:"timed_out,omitempty"`
}

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.