runtime

package
v0.3.35 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2026 License: MIT Imports: 28 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
)
View Source 
const TranscriptMessageKindCompactionSummary = "compaction_summary"

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
}

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"`
	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)
	ReadThread(context.Context, ThreadID) (ThreadSnapshot, error)
	RunTurn(context.Context, RunTurnRequest) (TurnResult, error)
	RetryTurn(context.Context, RetryTurnRequest) (TurnResult, 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)
	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
	IDGenerator        func(string) string
	LoopLimits         LoopLimits
	SubAgentRunTimeout time.Duration
	Capabilities       CapabilityOptions
}

type ListSubAgentDetailEventsRequest added in v0.3.21 

type ListSubAgentDetailEventsRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  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
	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 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 ProjectedCompactionSummaryRequest added in v0.3.20 

type ProjectedCompactionSummaryRequest 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"`
	History              []TranscriptMessage  `json:"history,omitempty"`
	CompactedHead        []TranscriptMessage  `json:"compacted_head,omitempty"`
	RetainedTail         []TranscriptMessage  `json:"retained_tail,omitempty"`
	Policy               config.ContextPolicy `json:"policy,omitempty"`
	Trigger              string               `json:"trigger,omitempty"`
	Reason               string               `json:"reason,omitempty"`
	Phase                string               `json:"phase,omitempty"`
	PreviousCompactionID string               `json:"previous_compaction_id,omitempty"`
	PreviousSummary      string               `json:"previous_summary,omitempty"`
	ContextUsage         config.ContextUsage  `json:"context_usage,omitempty"`
	Details              map[string]string    `json:"details,omitempty"`
}

type ProjectedCompactionSummaryResult added in v0.3.20 

type ProjectedCompactionSummaryResult struct {
	Summary string            `json:"summary"`
	Details map[string]string `json:"details,omitempty"`
}

type ProjectedContextCompaction added in v0.3.27 

type ProjectedContextCompaction struct {
	OperationID             string              `json:"operation_id,omitempty"`
	RequestID               string              `json:"request_id,omitempty"`
	Source                  string              `json:"source,omitempty"`
	CompactionID            string              `json:"compaction_id,omitempty"`
	PreviousCompactionID    string              `json:"previous_compaction_id,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"`
	CompactedThroughEntryID string              `json:"compacted_through_entry_id,omitempty"`
	Summary                 string              `json:"summary,omitempty"`
	SummarySchemaVersion    string              `json:"summary_schema_version,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"`
	UsageBefore             config.ContextUsage `json:"usage_before,omitempty"`
	UsageAfter              config.ContextUsage `json:"usage_after,omitempty"`
	Details                 map[string]string   `json:"details,omitempty"`
	CreatedAt               time.Time           `json:"created_at,omitempty"`
}

type ProjectedContextCompactionRequest added in v0.3.27 

type ProjectedContextCompactionRequest struct {
	RunID                 RunID
	ThreadID              ThreadID
	TurnID                TurnID
	TraceID               TraceID
	PromptScopeID         PromptScopeID
	History               []TranscriptMessage
	Labels                RunLabels
	PreviousProviderState *ModelState
	Reasoning             ReasoningSelection
	ManualCompaction      ManualCompactionRequest
}

type ProjectedContextCompactionResult added in v0.3.27 

type ProjectedContextCompactionResult struct {
	RunID            RunID                        `json:"run_id,omitempty"`
	ThreadID         ThreadID                     `json:"thread_id,omitempty"`
	TurnID           TurnID                       `json:"turn_id,omitempty"`
	Status           string                       `json:"status"`
	Error            string                       `json:"error,omitempty"`
	Metrics          RunMetrics                   `json:"metrics"`
	ActiveTranscript []TranscriptMessage          `json:"active_transcript,omitempty"`
	Compaction       *ProjectedContextCompaction  `json:"compaction,omitempty"`
	ProviderState    *ModelState                  `json:"provider_state,omitempty"`
	ActivityTimeline observation.ActivityTimeline `json:"activity_timeline"`
}

func CompactProjectedContext added in v0.3.27 

func CompactProjectedContext(ctx context.Context, opts ProjectedTurnOptions, req ProjectedContextCompactionRequest) (ProjectedContextCompactionResult, error)

type ProjectedTurnCompactionSummarizer added in v0.3.20 

type ProjectedTurnCompactionSummarizer interface {
	GenerateCompactionSummary(context.Context, ProjectedCompactionSummaryRequest) (ProjectedCompactionSummaryResult, error)
}

ProjectedTurnCompactionSummarizer lets a host provide only the summary text for a projected-turn compaction. Floret still owns cut-point selection, checkpoint message construction, generation/window metadata, and lifecycle events.

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
	CompactionSummarizer ProjectedTurnCompactionSummarizer
	ManualCompactions    ManualCompactionSource
}

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
	Reasoning             ReasoningSelection
}

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"`
	ProviderState      *ModelState                  `json:"provider_state,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 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
}

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 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 {
	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 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"`
}

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"`
	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"`
	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 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"`
	Kind                 string `json:"kind,omitempty"`
	EntryID              string `json:"entry_id,omitempty"`
	ParentEntryID        string `json:"parent_entry_id,omitempty"`
	CompactionID         string `json:"compaction_id,omitempty"`
	CompactionGeneration int    `json:"compaction_generation,omitempty"`
	CompactionWindowID   string `json:"compaction_window_id,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.

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.